--- sidebar_position: 1 --- # Create a Researcher Account The goal of Avicenna is to help you integrate smartphones, the web, sensors, and big data into your health research. This guide will demonstrate how to create a Researcher Account in Avicenna. Then, we will familiarize you with the features offered in the researcher dashboard. ## How to Create a Researcher Account To create a researcher account, you need to navigate to [Avicenna’s Welcome page](https://avicennaresearch.com/app/dashboard/auth/welcome) and click on _Sign Up_. ![Avicenna's Welcome Page](/assets/getting-started-welcome-page.png) In the next window, select the `You are a Researcher` button that leads to a page in which you can enter some basic information including your name, organization, email address, and password. ![Select You are a Researcher](/assets/getting-started-sign-up-as-researcher.png) ![Enter Your Basic Information](/assets/getting-started-enter-basic-information.png) After entering the required information and pressing `Sign Up`, you will be taken to the _Researcher Dashboard_. At this stage, given that your email address is not verified yet, you are not allowed to create a study or modify the features of the dashboard. This is also indicated at the bottom of the page via an alert. To verify your email address, tap on `Open Settings` at the bottom-right corner of the page. ![Verify Your Email Address](/assets/getting-started-verify-email-address.png) Then you should click on `Verify` for your email address. Following this, Avicenna will email you a verification code you need to enter in the provided space. As soon as you enter the correct code, you will receive a message at the bottom of the page, reading that the email address has been verified. ## Features in the Researcher Dashboard The researcher dashboard provides you with several features that are displayed in the left-side panel. These features include: - **My Studies page** which lists all of your studies. - **Basics page** which presents general information and settings of the currently selected study. - [**Activities page**](../reference/activities) which allows you to create, delete, or configure your research activities. - [**Data Sources page**](../reference/data-sources) which allows you to add, remove, or modify your data sources. - [**Notifications page**](../reference/study-setup-and-deployment/notifications.md) where you can create notification templates to automatically inform your participants as well as researchers of the research activities or specific events. - [**Researchers page**](../reference/study-setup-and-deployment/roles-and-permissions.md) which allows you to add or remove researchers and adjust their roles and permissions. - [**Participation page**](../reference/study-setup-and-deployment/participation.md) in which you will have access to the list of all the participants and all the functionalities related to that including invitations. - [**Activity Sessions page**](../reference/activities/activity-sessions.md) which provides you with information regarding your past, ongoing, and upcoming activity sessions. - [**Audit Trail page**](../reference/study-setup-and-deployment/audit-trail.md) where you can see and filter the history of all the activities related to your research participants. - [**Chat page**](../reference/study-setup-and-deployment/televisit.md) provides a means of communication between researchers and participants. Note that to use this feature, you should first contact Avicenna's support team. - [**Survey Responses page**](../reference/surveys/view-responses.md) in which you will be able to check the participants’ responses to all the research survey activities. - [**Data Export page**](../reference/analysis/raw-data.mdx) which enables you to see the requested exports from different research data and also export the sensor data. - [**Kibana**](../reference/analysis/kibana-basics) in which you can visualize your data and generate reports. Note that to access most of the above pages, you must first create a [new study](your-first-study.md). Besides the main features, the researcher dashboard also includes: - **Resource Hub** which is a list of useful links and resources like Forum, What's New, and Support email address. - **Profile** which allows you to change the settings of your researcher account. ## Troubleshooting ### I didn't receive the verification email Short delays might be OK, but for longer delays: 1. Make sure you actually started the verification process from the `Personal Information` page under the profile settings if you're a researcher and from the `Account Information` page under `Settings` if you're a participant. Avicenna doesn't send the verification email automatically after you sign up. 2. Check for typographical errors in the email address you used for your Avicenna account. 3. Check your Spam or Junk folder. Some email providers might have more restrictive rules, or you might have marked one of our previous emails as spam/junk. 4. Check if you applied some filters to your emails and whether Avicenna emails might automatically be moved to specific folders, or even auto-deleted. --- sidebar_position: 2 --- # Your First Study In the following sections, we'll guide you through setting up your study in Avicenna, programming Surveys, adding data sources, enrolling participants, and checking the incoming data. Each of these steps has tons of details to discuss, but we will skip over those. You can check the [Reference](../category/reference/) documentation for a more in-depth look at these topics. We still may use a term here or there that might be unfamiliar. In this case, please check our [Terminology](../reference/terminology.md) to find out what they mean. ## Create Your First Study After creating a [Researcher Account](../getting-started/create-a-researcher-account.md), you can navigate to `My Studies` located on the Researcher Dashboard. There you will see the `Create Study` button. Click on it to create your first study. You will see a page like the picture below: ![Creating a new study in Avicenna - First Page](/assets/getting-started-creating-new-study-first-page.png) You will be asked a few questions regarding your study. Start by picking a name for the study, for example, _My Health Pal_. Then enter the name of your organization, for example, _Avicenna Research_. Then enter the consent materials you want to be presented to the participants before joining the study. Avicenna asks participants to consent to these before they can register for your study. Then you can choose what time you expect participants to start their participation, what time their participation is expected to end, and how many days they are expected to be part of the study (Participation Duration). You can read more details in the [Participation Period](../reference/study-setup-and-deployment/participation-period.md) article on how the combination of these values allows you to configure the participation period of your participants. In this case, we want our participants to start their participation as soon as they join the study, and continue their participation for 14 days. We don't want to have a specific end date for our enrollment either. So leave the Participation Start Time and Participation End Time blank, and check the 'Open' checkboxes. In the next section, set the Participation Duration to 14 days. When done, click on `Start` to create your study: ![Review Study Settings before creating your study](/assets/getting-started-study-preview.png) When your study is created you will be taken to your study's `Basics` page. Here you can modify the values you entered above, add your colleagues to the study, or other basic configurations. ![Basics page of the study](/assets/getting-started-study-basics-page.png) ## Add Data Sources Your study likely will collect survey responses, sensor data, and other components. We discuss these in the following pages. For now, let's add a few data sources to our study. For this example, we want to collect GPS and pedometer data. So click on the Data Sources on the left panel, and then click on `Add New Data Source`: ![Add a new data source to your study](/assets/getting-started-select-data-source.png) In the list, find `GPS` and click on it. On the next page, specify whether providing this data is mandatory for your participants, or they can opt out as well: ![New data source Settings](/assets/getting-started-data-source-settings.png) You can also enter a name and a description to be shown to the participants. Follow the same steps to add a `Pedometer` as well. When done, your list of data sources should look like the following. Note that by clicking on the three dots you can edit and remove the selected data sources, and go to the Data Export page. ![The Final list of data sources for your study](/assets/getting-started-data-sources-list.png) ## Enroll Participants Now you are ready to enroll participants in your new study. You can read about different ways to enroll participants in the [Enrollment](../reference/study-setup-and-deployment/enrollment.md) section. Here we send the study URL to the new participants. To begin enrolling your participants, click on the `Invite Participants` on the Participation page and select the `Copy Registration URL`. The URL for our study is (yours will be different): - [https://avicennaresearch.com/study/3149/](https://avicennaresearch.com/study/3149/) Below, we pretend to be a participant who uses an Android device. Note that similar steps are true if a participant uses Avicenna for iOS or Avicenna for Web. As a participant, I receive the study Registration URL, and open it on my phone's browser: ![Participate in the study](/assets/getting-started-participate-in-study.png) If the participant does not have the Avicenna app installed, clicking on `Participate` will take them to the Google Play Store app and asks them to install the Avicenna app: ![Avicenna app in the Google Play Store](/assets/getting-started-avicenna-app-play-store.png) When the participant installs the app and opens it, Avicenna asks them to either login or sign up to join in your study: ![Welcome to the Avicenna page](/assets/getting-started-welcome-to-avicenna-page.png) After the sign-up and going through the introduction pages, the participant will see the study registration page in the app. This page shows different information about your study, such as name and organization, participation duration, and consent materials. ![Register in the study](/assets/getting-started-register-for-study.png) Clicking on `Participate` will enroll the participant in the study to start their participation: ![Avicenna participant app](/assets/getting-started-participant-app.png) The top banner on the homepage of the app asks the participants to perform some additional steps to complete their enrollment. These steps depend on your study settings. As here we wanted to collect GPS and Pedometer, the steps ask participants to grant permissions for GPS and pedometer data collection, as well as adjusting the phone battery settings to allow Avicenna to run in the background. ![Disable battery optimization](/assets/getting-started-field-deployment-disable-battery-oprimization.png) ![Grant GPS permission](/assets/getting-started-field-deployment-grant-gps-permission.png) After completing these additional steps, the participant can close the app. The app continuously runs in the background, collects the data as instructed by the study, and uploads it to your researcher dashboard. You can check back after some time to see the received data. --- sidebar_position: 3 --- # Your First Survey ## Create Your First Survey In the previous section, we created our first study, added a few Data Sources, and enrolled as a participant. So far, our study collects sensor data behind the scenes and uploads it to the Researcher Dashboard. In this section, we'll expand our study by adding a few surveys. To start, navigate to the Researcher Dashboard, and from the left panel click on `Activities`. [Activities](../reference/activities/) are the tasks participants are asked to do during their participation, such as surveys, Matrix Reasoning tests, or Time Use diaries. Click on `Create New Activity`, and select `Survey` to create your new survey. After creating the survey, you will be taken to the Activity Editor interface: ![Creating your first Survey in Avicenna using Activity Editor](/assets/getting-started-your-first-survey.png) If you publish the survey as is, Avicenna would add a button to the home screen of the participant's app, labeled `New Survey Trigger`, and allow them to start the survey by tapping on it. Now, we want to rename this button to `Exercise Motivations`. So from the top part of the Activity Editor, open the `Triggering Logics` section, and click on the `Edit` button for the existing User Triggering Logic there: ![Button Caption for User Triggering Logic](/assets/getting-started-your-first-survey-user-triggering-logic-button-caption.png) Then modify the `Button Caption` box from `New Survey Trigger` to `Exercise Motivations`, and save the changes. Note that as you change your survey, it's saved automatically on the server. You can also save it by pressing the `Save` button in the top right corner. Switch to the `Content` page. You will see there is one _Information_ question already with [Question ID](../reference/surveys/questions.md#common-question-attributes) _1_. Click on the `Edit` button next to the question to start editing the question. Then change the content of the question to: ```text We wanted to know what motivates you to exercise every day. ``` We also want to add an image to our question's content. Click on the image icon on the text area toolbar to open the image selector. Upload the image you want to add to this question. Then click `Select` to choose this image. When done, you can click on the `Save` button to save the changes. ![Your first question in Activity Editor](/assets/getting-started-your-first-survey-first-question.png) Now we want to add a new question to this section. You can choose the question from the right-side panel, labeled `New Item`, and drag and drop it below the current question. Here we want to ask participants to take a picture of what motivates them to exercise, so we will use an _Image_ question with the following content: ```text Please take a picture or upload a photo of what motivates you to exercise. ``` We now should publish our survey to allow our participants to access it. To do so, go to the `Preview & Publish` section and click on the `Publish` tab on the left side. Then click on the `Publish` button. ![Publishing the Survey](/assets/getting-started-your-first-survey-publish.png) ## Respond to Survey As a Participant Let's go back to our dummy participant account and check our new survey there. As we chose Avicenna to update participants' devices as well during the publish, when you open the app now, you should see the button for your new Survey on the home screen of the app. ![Avicenna app presents our first Survey in the study](/assets/getting-started-participant-app.png) If you do not see this button, just close and reopen the app and the button should appear as above. Click on the `Exercise Motivations` button to open the survey in the app. You will see the first question and the image we added to it. ![Responding to the Survey in the Avicenna app](/assets/getting-started-your-first-survey-question-one.png) Press `Next` to go to the second question. In the second question, we are asked to either upload a photo from our device or take a photo with the camera. ![Image questions in the Avicenna app](/assets/getting-started-your-first-survey-question-two.png) Press `Submit` to finish the Survey and upload the responses. ## View Participant Responses Now let's switch back to our Researcher role, and check the response from our participant on the Researcher Dashboard. First, you need to go to the Activity Sessions page. This page allows us to see the activity sessions participants have had so far, or are scheduled to have in the future. On this page, you can filter the data based on `Participants` and `Activities`. You can also select a date range, which can be set to daily, weekly, monthly, or yearly views. ![Activity session results showing Surveys completed by the participants](/assets/getting-started-your-first-survey-activity-sessions.png) You can see above that participant ID 68576 has responded to survey ID 19448. You can see at what time the survey started and finished. On this page, you can see all sessions for all participants, whether those that are already past or the upcoming ones. For each session, the page shows their status, for example, completed, blocked, expired, or canceled. Now let's view the provided responses. On Researcher Dashboard, click on Activity Responses. On this page, we also should start by selecting the survey we want to look at. ![View the responded Survey in the Avicenna researcher dashboard](/assets/getting-started-your-first-survey-survey-responses.png) Note that you can click on each cell of the table to see more information. For example, clicking on the first cell of each column will show more details about that user. Clicking on each cell in the next columns shows the response of the participants to each question. --- sidebar_position: 4 --- # Triggering Logics In the previous section, we added an Activity to our study. Participants could respond to this Activity by tapping on its button on the home screen of their app. They could do it as many times as they wanted, and any time they wanted. In some cases, this is ideal, for example, if we are asking participants to report anything that motivates them to exercise. But in many cases, we may have certain conditions on when the Activity should be presented to the participants, how often it should be presented, and how much time participants have to complete the Activity. The logic that defines these is called `Triggering Logics`. Our previous Activity, `Exercise Motivations`, used a _User Triggering Logic_. It means participants decide when and how many times to trigger the Activity. That's why the button for the Activity is always on the home screen of the app. Avicenna supports other types of Triggering Logics as well. For example, a _Time Triggering Logic_ prompts the Activity based on a certain timetable. Another example is the _Proximity Triggering Logic_ which prompts the Survey based on Bluetooth-based sensor data. Or _Geo-fence Triggering Logic_ which uses GPS data for prompting a given Activity. You can read more about this in the [Study Activity](../reference/activities/) documentation. Here we continue our example study by adding a Survey Activity to it which is prompted _once a day_ at _7 pm_ and asks about their general health. To do this, we again go to the Activities page on the Researcher Dashboard and click on `Create New Activity` to create a new Survey. We call the Survey _Quality of Life_. In the Activity Editor remove the content in the description and delete the default User Triggering Logic. ![Triggering Logics tab in the Activity Editor](/assets/getting-started-triggering-logics-activity-editor.png) Then, in the Triggering Logic section, click on `Time` to add a new Time Triggering Logic. This dialog has many settings and we don't plan to go through all of them here. But we encourage you to read the details in the [Triggering Logics](../reference/activities/triggering-logics.md) section. For our use case here, we set the `Time Format` to `Relative` and `Base Time` to `Study Registration Date`. This way, all the calculations will be based on the midnight before the participant joined the study. For example, whether the participant joins at 10 am or 5 pm on Nov. 11th, the calculations will be based on Nov. 11th at 00:00. We also set the `First Trigger` to be on Day 1 at 19:00:00. We further set it to repeat once a day for 14 days. The image below shows the settings of our Triggering Logic. ![Configuring the Time Triggering Logic](/assets/getting-started-triggering-logics-configuring-time-triggering-logic.png) Now if you click on the `Test The Schedule` button, you can try out how Avicenna will calculate the Activity prompt time based on this setting. You can choose a date and time to represent a participation start time of a hypothetical participant, and Avicenna shows what time our Survey will be presented. For example below you can see that based on our settings, if a participant joins on Feb., 26th, at 9:15, they will receive Surveys on Feb., 27th at 19:00, Feb., 28th at 19:00, and so on. ![Example schedule of Time Triggering Logic](/assets/getting-started-triggering-logics-time-triggering-logics-schedule.png) Now if you click on the `Save` button in the Triggering Logic dialog, the new Triggering Logic is saved in our Survey. ## Notifications and Expiry Avicenna by default does not prompt any notification when an Activity is prompted. You need to create your _Notification Template_ and link it to your Activity as well. This will be explained in the [Notifications](../getting-started/notifications.md) section. If you need to know more advanced details on this matter, please refer to the [Notification](../reference/study-setup-and-deployment/notifications.md) article as it will teach you how to create a Notification Template and link it to your Activity. After linking the Notification Template to your Activity, we also want to give 1 hour to participants to complete each session of the Survey. If they don't complete a session within this 1 hour, we want it to be expired. To do so, go back to the `Contents` page and open the `Settings` tab on the lower right side of the screen. At the bottom of the Settings find the `Expiry Time` option, and set it to _After 60 minutes._ ![Setting the Expiry Time for the Survey](/assets/getting-started-triggering-logics-expiry-time-for-survey.png) ## Finishing the Survey In the last step, we add questions to our Survey. As this is about the quality of health, we use a horizontal [Visual Analog Scale (VAS)](../reference/surveys/questions.md#visual-analog-scale-vas) as shown below: ![Adding questions in the Activity Editor](/assets/getting-started-triggering-logics-adding-questions-activity-editor.png) Then we finish by publishing the Survey. When the Survey is published, Avicenna reloads the device for our current participants and schedules the Survey sessions for them every day at 7 pm. ## Checking Scheduled Sessions Unlike User Triggering Logic, if you check the app as a participant, you will not see any Survey waiting for your response. This is because the first Survey is supposed to be prompted at 7 pm, and be available for 1 hour. You will receive a notification at 7 pm when the Survey is available. But you can check the schedule Avicenna has for this participant via the `Activity Sessions` page. So let's go back to the Researcher Dashboard and click on `Activity Sessions`. Then choose our participant from the list, and from the list of Activities, choose the Survey we just created: ![Scheduled Surveys are shown on the Activity Sessions](/assets/getting-started-triggering-logics-scheduled-surveys.png) As you can see above, the participant starts receiving the Survey every day at 7 pm, starting from Day 1, and none of those Surveys are responded to yet. As the participant completes these Surveys, the status of these sessions is updated here. :::info Note that in some cases, the first prompt for the participants might start from day 2. This happens when participants join the study before a survey is added to the study, i.e. if by the time that you add a survey to your study, the participant is already on his or her second day of the study, Avicenna will prompt the survey from the second day. ::: --- sidebar_position: 5 --- # Notifications To get familiar with sending out notifications to participants for activities, navigate to the Activity Editor. Here, you will find a tab labeled `Notification Templates`. This tab brings you to the Notification Templates section, where you can manage notifications for the activity on which you are working. These templates automatically send out personalized messages, depending on the rules you set. To create your first notification template, click on the `Create Template` button. First, assign your template a `Label` for your tracking purposes. Following this, decide on the `Recipients` of the notification. Should it be a researcher who needs to stay updated or a participant whose engagement is crucial to your study? Next, under the `Notify On` option, choose the event that will trigger the notification. The Activity Editor allows you to choose events such as when a session is released, completed, expired, or canceled. Select the option that fits your needs. With Avicenna, you also get to decide when the notification should be sent. You can send it immediately when the `Trigger` event occurs or earlier or later. This is done by setting an offset. This option is useful, for instance, if you want to remind participants about an upcoming session. Then, choose the `Medium` and `Message` of the notification. We recognize that the purpose of notifications can vary. Some might require the formality of an email, some the urgency of an SMS, and others the convenience of an in-app notification. Decide on the medium for your notification and write a message that fits its purpose. If it's an email, consider an attention-grabbing subject line and an informative body. If it's an in-app notification, devise a short and engaging message. ![Create a new Notification Template](/assets/getting-started-notifications-create-notification-template-dialog.png) Once you've completed your Notification Template, you're ready to make it live. Just hit the 'Create' button, and your template will be created and added to your activity. Avicenna will create notifications based on this template and prompts them to the right recipient. To continue our example from the previous sections, we want to notify participants when a session is released using an In-app notification. To do so: 1. **Go to the Notification Templates Tab**: Inside the Activity, click on the `Notification Templates` page. 2. **Click Create Template**: Hit the `Create Template` button to open the dialog box for creating a new Notification Template. 3. **Label the Template**: Give your template a `Label`, for example, _Participant Notify - Session Released_. 4. **Define the Recipients**: In the Recipients section, choose `Participant`. 5. **Set the Notification Trigger**: Under `Notify On`, select `Session Released`. This means the notification will be sent when a new session is released for the participant. 6. **Select the Medium**: Choose `In-App` as the medium through which the notification will be sent. 7. **Write the In-App Notification**: Write the title and description of the in-app notification. For example, the title can be _New Activity Available!_ and the description can be _You have a new session available in Activity X. Open the Avicenna app to start!_ 8. **Finalize the Template**: Click `Create`. Your template is now active and will send an in-app notification to participants whenever a new session is released. ![Notifying a participant about a released session through In-app notification](/assets/getting-started-notifications-notify-participants-when-session-released.png) As another example, let's suppose we want to send a notification via Email to the researchers when a session is completed by any participant. To do so: 1. **Go to the Notification Templates Tab**: Inside the Activity, click on the `Notification Templates` page. 2. **Click Create Template**: Click on the `Create Template` button to open the dialog box for creating a new Notification Template. 3. **Label the Template**: Give your template a label, for example, _Researcher Notify - Session Complete_. 4. **Define the Recipients**: In the Recipients section, choose `Researcher`. Specify which researcher(s) should receive the notification - likely, this will be yourself or someone managing data collection. 5. **Set the Notification Trigger**: Under `Notify On`, select `Session Completed`. This means the notification will be sent when a participant completes a session. 6. **Select the Medium**: Choose `Email` as the medium through which the notification will be sent. 7. **Craft the Email**: Write the subject and body of the email. For instance, the subject can be _Session Completed_ and the body can contain details like _A participant has just completed a session for Activity X. Log in to Avicenna to review the data_. 8. **Finalize the Template**: Click `Create`. Your template is now active and will send an email to the specified researcher whenever a session is completed. 9. **Link/unlink your Notification Template**: The created notification template is linked to the Activity. If you want to unlink it or link another one, click on the `Unlink`, and `Link` buttons respectively. ![Notifying a researcher about a completed session through an Email notification](/assets/getting-started-notifications-notify-researcher-when-session-completed-via-email.png) --- sidebar_position: 6 --- # Criteria So far, we have created a new study in Avicenna and added a few data sources to it to collect sensor data. In this section, we will learn how to use the powerful `Criteria` feature in Avicenna. We also added a few surveys and configured them both to be triggered by the participant at any time or to be triggered at a certain time. Here we want to discuss another powerful feature in Avicenna called `Criteria`. Criteria is a condition that you assign to a part of your study, and they enable or disable that part depending on whether they are evaluated as `True` or `False`. Avicenna continuously evaluates the Criteria set in your study for each participant using their most recent responses and prompts each participant with the components that are evaluated as `True`. This way, you can create a personalized experience for your participants. You can assign Criteria to an Activity, to a Triggering Logic, to a section of your survey, or to a single question. Here we should know how Criteria can be used in our demo study. So far, we added a survey with a User-Triggered Triggering Logic that asked participants to share their motivation for exercise. We will add another survey and ask about their nutrition habits. Then we add a third survey that asks participants whether they want to participate in the Exercise Motivation part of the study, the Nutrition Habits part of the study, or both. So let's go back to the Researcher Dashboard and click on Activities. Then [create a new survey](your-first-survey.md) by clicking on the `Create New Activity` button. We assume you are already comfortable with creating a survey in Avicenna. So we just go ahead and create one survey with the following configurations: - User-Triggered Triggering Logic with the button caption set to `Food Diary`. - Starts with an `Information` block telling participants: "We want to know more about your dietary habits." - Add an `Image` question that asks "Please share a picture of the food or snack you are having." Now go back to the Activities page, and add a new survey, with the following settings: - User-Triggered Triggering Logic with the button caption set to `Select Your Survey`. - Add just one Multiple-Answer question on the `Content` page asking: "Which part of the study do you prefer to participate in?" - Add two choices to your question: Exercise and Nutrition. So your survey's question flow should look like the following: ![Question to ask participants to choose their survey](/assets/getting-started-criteria-survey-selector.png) Take note of the ID of the question. Here the ID of the question is 1 (Q1). Also, note the ID of the choices you added. In the above example, `Exercise` is answer ID 1 (A1), and `Nutrition` is answer ID 2 (A2). Publish the survey and go back to the Activities page. Your Activities page should now look like the following: ![Activities list](/assets/getting-started-criteria-activities-list.png) Pay attention to the ID of each survey. You need these to set up your Criteria. Your survey IDs definitely will be different from the ones we see in this example. For our example here, the IDs are as follows: - ID 18345: Exercise Motivations - ID 18347: Quality of Life - ID 18350: Nutrition Habits - ID 18351: Survey Selector Now we want to change the Exercise Motivations such that it's only shown if the participant chooses `Exercise` as their answer to Question ID 1 of survey ID 18351. We also want the Nutrition Habits to be shown only if the participant chooses `Nutrition` as their answer to Q1 of ID 18351. To do this, open the Exercise Motivations survey and navigate to the Triggering Logics page. Click the 'Edit' button for the User Triggering Logic. In the Criteria section, click 'Set.' A dialog box will appear. Enable 'Typing Mode' and enter `Q18351_1 == 1` (note that the IDs will vary for your specific example). ![Criteria for the Exercise Motivation survey](/assets/getting-started-criteria-for-exercise-survey.png) This means the Triggering Logic should be enabled and accordingly the survey will be prompted to the participants, only if the participant chooses Answer ID 1 (i.e., `Exercise`) as part of their response to Question ID 1 of survey Activity ID 18351. Save the change to the Triggering Logic, then save and publish the survey, and navigate back to the Activities list. Then follow the same steps for the Nutrition Habits survey, and set the Criteria for its Triggering Logic to `Q18351_1 == 2`. ![Criteria for the Nutrition Habits survey](/assets/getting-started-criteria-for-nutrition-survey.png) Save the changes to the Nutrition Habits survey. Now we are done with the changes, we can check out the changes to our study. ## Try As a Participant Let's check the participant's experience of the changes we made above. Switch back to the app where you had logged in as a participant. You should see that the button for `Exercise Motivation` is removed and a new button is added that is called `Select Your Survey`. ![Avicenna app shows the Select Your Survey button](/assets/getting-started-select-your-survey-button.png) If you do not see these, it might be because the study settings are not reloaded on your phone just yet. To force-reload, the settings, open the app, go to Settings -> My Studies, and tap on _Reload Studies from Server_. Here you can see that none of the buttons for the Exercise or Nutrition Surveys are shown. That's because, as a participant, we have not answered the survey Selector question. Therefore, Avicenna finds no answer to Question ID 1 of survey ID 18351 and evaluates the Criteria to `False`. Click on the "Select Your Survey" button and choose one or both of the presented options. Here we are choosing both "Exercise" and "Nutrition". Press `Submit` to save the survey and return to the app's home screen. Depending on your response, different Surveys are shown on the home screen. ![The Avicenna app shows both the Exercise and the Nutrition button](/assets/getting-started-exercise-and-nutrition-buttons.png) That's because we chose both options and therefore both `Q18351_1 == 1` and `Q18351_1 == 2` were evaluated as `True`. You can click on the `Select Your Survey` button as many times as you like, and change your options. Your option is immediately applied to the home screen of the app. ## Other Uses of Criteria In the above example, we used the Criteria on a User Triggering Logic. This helped us to see immediately how the Criteria work in action. You can use Criteria on many other components. For example, if you put Criteria on a survey section, Avicenna evaluates the Criteria immediately before presenting that section to the participant, and depending on the result of the evaluation, it either skips the whole section or shows the section to the participant. Similarly, you can put Criteria on a single question to present or skip that question. You can also include both positive and negative values in your criteria. For example, a condition like `Q58_31 == -10` or `Q1_3 > -5` can be used, where `-10` and `-5` are negative values. Another useful use of the criteria is Time Triggering Logic. This defines if Avicenna should present a survey or not and if yes when the survey should be presented. --- sidebar_position: 7 --- # Field Deployment After you've configured your study, added the necessary data sources, and programmed the Surveys and Matrix Reasoning tests, you are ready to enroll participants and collect data. In this section, we'll cover the important checks before enrolling participants and provide some tips for field deployment. ## Test Before Deploy Avicenna provides countless features, each having a high level of flexibility, and you need to make sure the configuration you have set is exactly what you intended. So it's very important that after you finish designing your study in Avicenna and before the field deployment, you test the study to ensure all components behave as expected. As a rule of thumb, you should test the following aspects of the study before the field deployment: - Is the Participation Period for each participant correctly configured? - Have you included all the data sources you need for the study? Are there any missing or extra data sources? Also, what does the data collected from each data source look like? - Is the flow of each survey correct? Are skip patterns configured as you intended? - Have you configured the Triggering Logics for each survey correctly? Are time-triggered Surveys, or proximity-triggered Surveys prompted at the right time? We suggest conducting the test in two phases. First, after completing the design of the first draft of the study, test the study by yourself. This allows you to tweak different components, and test it again right away on your phone. After you are sure the study works as you expect, you can conduct the second phase of testing by inviting your friends, and colleagues to join your study as dummy participants. This allows you to mock a complete field deployment and pinpoint any minor adjustments missing from your first round of tests. ### Test Accounts As a researcher, you probably have a [Researcher account](../reference/terminology.md#researcher) with Avicenna which you use to create and manage your study. Avicenna does not allow _Researchers_ to join a study as a participant. You should create another account as a _Participant_, using a different email address, and use that to test your study. Ideally, you use your professional email address for your _Researcher_ account and your personal email address for your _Participant_ account. You may also decide to use email aliases, such as [+ postfix](https://gmail.googleblog.com/2008/03/2-hidden-ways-to-get-more-from-your.html) instead. During the test and as you make changes to the study, it's good practice to drop the participant and do your test again. You can do that using the [Drop From Study](../reference/study-setup-and-deployment/participation.md#drop-from-study) option on the `Participation` page. This option does not remove the participant's account. So you can use these credentials again. But it removes the participation record and any data associated with this. So you can join your study again as if it's the first time. ### Test Participation Period In the previous section, we discussed how you can set `Start Time` and `End Time` to instruct Avicenna how long each participant should be part of your study. If you want to make sure the values you have chosen for these parameters are correct, use your Participant account to register in your study, and then check out the calculated Start and End Time that Avicenna has assigned to you. To do so, select your study in `My Studies`, navigate to the Participation page, and check the participants' `Start Time` and `End Time`. ![Testing the participants' participation period](/assets/getting-started-field-deployment-testing-participation-period.png) The `Start Time` and `End Time` fields show the values you are looking for. In the above example, our first participant will be part of the study from `2023-06-11` to `2023-06-18`. All Activity sessions (e.g., Surveys, or Matrix Reasoning tests) and sensor-based data collection from this participant will happen within this period, and no data will be collected before or after this time window. ### Test Data Sources While collecting data from the data sources you have chosen is done fully automatically, it's important to test a few things about them before the field deployment. First, you should make yourself familiar with the setup and permission requirements for each of the data sources in your study. Some data sources work without any explicit permission from the participant such as [raw motion sensors](../reference/data-sources/from-smartphone/motion-sensors.mdx#accelerometer). Others require the participant to give explicit permission to Avicenna to access the data, for example, [GPS](../reference/data-sources/from-smartphone/location.mdx#gps). Some other data sources may require the participant to install another Avicenna application on their phone for the data to be collected. Participants have to do these setups once immediately after they join your study. They do not need to repeat these unless they explicitly revoke permission to switch to a new device. The Avicenna app will walk them through the steps needed for each configuration:
![Grant GPS permission](/assets/getting-started-field-deployment-grant-gps-permission.png) ![Disable battery optimization for the Avicenna app](/assets/getting-started-field-deployment-disable-battery-oprimization.png)
When you join your study as a mock participant, you will be able to check out all these steps. This allows you to better guide your participants during the enrollment session, in case they have any questions. Second, you need to check the data collected from each data source, and how they look like. To do so, you need to remain in the study for a few hours or even days so enough data is being collected. Then you can go to your Researcher Dashboard and check out the data collected from your participant account. In the [next section](data-access-and-visualization.md), you can read more about how you can access the data in the Researcher Dashboard. ### Test Survey Flow Avicenna Activity Editor allows you to preview the survey and test how it will work on the participants' devices. To do so, go to the `Preview & Publish` page of the Activity Editor. The `Preview` tab there allows you to quickly test your survey flow. ![Test Your Study Survey Flow Using Online Survey Preview](/assets/getting-started-field-deployment-testing-survey-flow.png) While Survey Preview gives you an overall feeling about your survey flow, it's important to test the flow on a smartphone. If possible, we suggest testing it on all platforms that your participants may use: Android, iPhone, and/or the web. This way you can be sure the content and the flow of your survey are properly programmed. The challenge is using specific [Triggering Logics](../reference/terminology.md#triggering-logic) and instructing your survey to be prompted at a certain time based on either proximity or any other contextual Triggering Logics. In this case, when you join the study as a participant, you have to wait for a while before the Avicenna app prompts your survey for you to test it. This gets even worse when you have multiple Surveys, each with different Criteria, where the Criteria impact the Triggering Logics. Testing this can easily get very complex. The ideal solution is to first test the flow of the survey, and then test the Triggering Logics separately, as explained below. To test the flow of the survey, simply add a [User Triggering Logic](../reference/terminology.md#user-triggering-logic) to each of your Surveys. This way, you instruct Avicenna to add a button to the app's home screen for each of your Surveys. Using the survey's triggering button, you can initiate the survey as many times as needed. The following image shows how the home screen of the Avicenna app looks like after we added a [User Triggering Logic](../reference/terminology.md#user-triggering-logic) to each of the four survey activities we created for our demo study. ![Test your study Survey Flow using User Triggering Logics](/assets/getting-started-field-deployment-testing-survey-flow-user-triggering-logics.png) This way, you can launch each survey as many times as needed, even Surveys that are supposed to be prompted at certain conditions. When you have tested the flow of the survey and are happy with how questions are presented and how the skip patterns and branchings work, you can remove all User Triggering logics you had added for testing. ### Test Triggering Logic In addition to the flow of your survey, you also need to make sure each survey is triggered exactly at the intended time. Avicenna offers different Triggering Logics you can use throughout your study. Here we discuss how you can test each type. #### User Triggering Logics Surveys with User Triggering Logic are simple to test. Avicenna should present a button on the homepage of the app, and tapping on that button should open the intended survey. #### Time Triggering Logic When you assign a Time Triggering Logic to a survey, you instruct Avicenna to notify participants based on a certain schedule and ask them to complete the survey. In this case, it's very important to make sure the defined schedule is exactly what you had in mind. Such a schedule can be as simple as _every day at 9 am_ or as complex as _if the participant is female, on Mon., Wed., and Fri. between 6 to 7 pm_. When a new participant joins your study, for each survey with Time Triggering Logic, Avicenna generates the timetable for survey prompts and uses that to prompt the survey. You can check that timetable right after the participant registers in your study, to ensure the generated survey prompt times are what you expect. To do so, from the Researcher Dashboard, select your study and navigate to the `Activity Sessions` page. There, you can select one or more participants, and one or more Surveys, and check all sessions for that survey. If a session was expected to be prompted in the past, Avicenna will also display whether the participant responded to it, canceled it, or the survey was expired. If the survey session is in the future, you can check when the survey is expected to be prompted. The following image shows the participant who has registered in our demo study. We configured our "Quality of Health" survey to be prompted once a day at 11 am. You can see that the timetable below shows the first survey session was prompted on March 6th, the second session will be prompted on March 7th, and so on. ![Testing your study's Time-Triggered Survey](/assets/getting-started-field-deployment-testing-survey-time-triggering-logic.png) Every time you modify your survey's Triggering Logic, Avicenna updates this timetable accordingly. #### Proximity Triggering Logic You can define Surveys in Avicenna that are prompted based on a participant's proximity to another participant, an object, or a place in the physical world. To use this survey, your study should be configured for proximity monitoring via Bluetooth Beacons, [as discussed here](../reference/data-sources/from-smartphone/contact-network.md#bluetooth-beacons). When you configure your study for Beacon-based proximity monitoring, you will specify what are the `Teams`, `Roles`, and `Subjects` in your study. Later on, you will use this information to configure your survey's Proximity Triggering Logic. Assuming you have set up that part successfully, testing your survey prompt involves configuring your beacons and placing them where appropriate, and then using your phone logged in with your participant account to come into proximity of these beacons and leave their proximity. If the phone detects a long enough proximity session with the beacon, you will receive a survey on your phone. We suggest you check out [this article](../reference/analysis/kibana-basics/proximity-survey-in-kibana.md) on how you can investigate exactly why a given Proximity Triggering Logic survey was prompted or was not prompted on every given occasion. ## Participant Enrollment After fully testing your study, you can start enrolling participants and collecting the data. You can do that by sharing the study registration information with prospective participants and asking them to enroll in your study. In the [Enrollment section](../reference/study-setup-and-deployment/enrollment.md), we discuss how participants can find and join your study. You can also invite participants to your study. Participant invitation is available regardless of whether your study is [Invitation-based](../reference/study-setup-and-deployment/enrollment.md#invitation-based) or [public](../reference/study-setup-and-deployment/enrollment.md#public). Please check the [Invitation section](../reference/study-setup-and-deployment/enrollment.md#invite-participants) for more details on how to invite participants to your study. ## Check Incoming Data While your study is in progress, we encourage you to use the Researcher Dashboard and check the status of your participants daily. This ensures that if your compliance drops or any issues happen, you can detect and stop it as soon as possible. The following checklist is a good starting point on the items that you should check regularly while collecting data for your study: - **Is there any participant who has not responded to their Surveys for a long time?** In this case, you may want to follow up with the participant regarding the reasons for the low compliance. - **Are sensor data uploaded at the expected rate?** You can check this using the [In Operation metric](../reference/study-setup-and-deployment/participation.md#in-operation-event-plots) on the _Participation_ page. - **What does the incoming sensor data look like?** Access the sensor data uploaded by the participants and ensure they are as expected. - **What do the incoming survey responses look like?** Check the responses that participants have provided since they joined the study. ## Changes to In-Progress Study (Mid-Study Changes) Mid-study changes are adjustments made after participant enrollment begins, including modifying survey schedules or skip patterns, adding/removing data collection types, or updating consent materials. In Avicenna, these challenging yet inevitable modifications (especially in complex studies) are managed through a synchronization system that ensures current participants' devices maintain updated study settings from the server with minimal disruption to ongoing data collection. If you adjust the study's basic configuration, such as name or consent form, this will be sent to the current participants without interrupting their current participation. Similarly, changes to the data sources, including adding a new data source or removing an existing one, will be applied to the current and prospective participants without any interruption. If you change the study's Participation Period settings, this will not impact the current participants and will only be applied to the new participants. If you want to modify the participation for the current participants, you can do so using the [Modify Participation Period](../reference/study-setup-and-deployment/participation.md#modify-participation-period) option on the _Participation_ page. This change instructs Avicenna to reschedule the surveys with _Time triggering logic_ if any. So after making this change, make sure to [check the schedule for the time-triggered surveys](#time-triggering-logic). If you make any changes to the survey content, the change is applied to all participants immediately after publishing the changes to the survey. If you make changes to the survey's Time Triggering Logic, that will change the upcoming scheduled sessions. In this case, you should check the new schedule as described in the above paragraph. In all cases, don't forget to [reload the device for all participants](../reference/study-setup-and-deployment/participation.md#reload-devices) so they receive the changes immediately. --- sidebar_position: 8 --- # Data Access & Visualization Shortly after starting the enrollment and as participants provide the data to your study, you can access the data and start the analysis. You can review the data on the Researcher Dashboard, use Avicenna's integrations to query and visualize the data, or export the data and use it in other tools. We discuss each of these below. ## Activity Responses Immediately after a participant completes an [Activity session](../reference/terminology.md#session), Avicenna uploads the responses to the server and makes them available to your research team. At any time, you can check the status of the sessions in your study using the `Activity Sessions` page. For survey activities, you can also check the responses on the `Activity Responses` page. ![View the responded data source in the Avicenna Researcher Dashboard](/assets/getting-started-data-access-and-visualization-survey-responses.png) On this page, you can also choose to export the data as CSV for the chosen data source, all data sources, or all of the Activities. This process happens in the background and you will get an email as soon as the export is completed. You can always check the status of your export, or download the data via the Data Export page. ## Exporting Data You can use the `Data Export` page to export collected sensor data in a different format. ![Avicenna Data Export page](/assets/getting-started-data-access-and-visualization-data-export.png) In order to export the data, you should select one or more participants and a data source. Depending on the type of data you are exporting, Avicenna offers one or more different formats. You always have the option to export as `CSV`, but for example, for GPS you may choose to export as `KML` or `GPX` as well. Further, you have to choose a date range for which you want to export the data. When done, click on the `EXPORT` button to start the data export process. ![Data Export process](/assets/getting-started-data-access-and-visualization-data-export-process.png) Export files can be very large, sometimes up to multiple gigabytes. Avicenna will send you an email when the export is ready. Then you can download the resulting file from the Data Export page. Each data export is available for 7 days. Data exports older than 7 days are removed automatically and you can create them again if needed. ## Visualizing Data Avicenna allows you to access your data directly from the Researcher Dashboard, using Avicenna integration with the [Kibana visualization tool](https://en.wikipedia.org/wiki/Kibana). You can use this tool to query your raw data and visualize them in different forms. Below we will give you a quick introduction to how you can use this tool. You can learn more on [Data Visualization via the Kibana](../reference/analysis/kibana-basics/) page. To access Kibana, on the Researcher Dashboard and from the left-side panel, click on `Kibana`. You will be taken to a new page as shown below. ![Accessing Kibana](/assets/getting-started-data-access-and-visualization-kibana-discover-page.png) On the top left corner, you can choose the data table (or _Index Patterns_, as it is called in Kibana) you want to connect to. The names are self-explanatory, and you should be able to easily find the data index you want to explore. By default, as you see above, you are connected to the `Bluetooth` index. You also should choose a date range for which you want to see the data. By default, the date range filters only for the data that are received within the past 15 minutes. So chances are that you will see no data on the page. Here, we change this to the last two weeks. ![Selecting time range](/assets/getting-started-data-access-and-visualization-kibana-time-range.png) As you can see, within this time window, our study has collected 963 GPS records. ![Exploring GPS data via Kibana](/assets/getting-started-data-access-and-visualization-kibana-gps-data.png) You can filter the data based on any criteria, create graphs and visualizations based on this data, or create data dashboards by putting together your visualizations. We encourage you to read more about how you can use Kibana to visualize your study data in the [Data Analysis](../reference/analysis/kibana-basics/) documentation. ### Audit Trail Regardless of the type of study you are conducting via Avicenna, your study will involve a set of participants. For every participant in your study, Avicenna records all of their interactions with the app and reports it in real-time, as part of the Audit Logs. You can check these logs for each participant to help them navigate your study, or to troubleshoot the issues they might have, or just to use them at a later time as metadata during the analysis. You can access the Audit Logs in Kibana via the `audit trail` index. To do so, on the Researcher Dashboard, click on `Kibana` on the left-side panel, and select the `audit-trail` index. We just change the time range to `Last 30 days`: ![View Participant Audit Reports data in Kibana](/assets/getting-started-data-access-and-visualization-kibana-audit-trail-index.png) From the list of data fields on the left side, we click on `user_id`, `device_id`, `audit_log_type_name`, and `message`. We also click on the `record_time` column's title to change the sorting order to `Sort Old-New`. Now our report looks like the following: ![Filtering Audit Logs data in Kibana](/assets/getting-started-data-access-and-visualization-kibana-audit-trail-filter-reports.png) Above you can see different events that have happened, such as _Participant read their registration status_, _Researcher opened the Basics page_, and _Notification updated_. You can refer to the [Audit Trail](../reference/study-setup-and-deployment/audit-trail.md) for more details on what pieces of information are available, and how they can be interpreted. ## Where to Go Next? In the previous sections, we learned some basic skills on how Avicenna works. We created a simple study and configured it to collect different types of sensor data. We programmed a few data sources and tried them out in the Avicenna app. We configured when and how often the data source should be prompted. We learned how to use the Criteria to add branching and skip patterns to our study. We explained what you should test before going to the field deployment, and what you should look out for while in the field. And lastly, we discussed how you can access your data and visualize them. This should prepare you to start using Avicenna for your study. As you work with different parts of the system, we suggest referring to the Reference Documentation from the left panel to learn the details of how the relevant features work. You can also refer to the Tutorials for different recipes and how-to articles. If you have any questions, you can always ask that in our [forum](https://forum.avicennaresearch.com). You can also email us at [support@avicennaresearch.com](mailto:support@avicennaresearch.com). --- sidebar_position: 1 --- # Why Avicenna? Many software packages claim they offer a full suite of capabilities for experience sampling studies, ecological momentary assessments, or more generally to create websites and apps for human-subject research. If you check out their website, they each make many claims about the wide range of features they support, the high-quality service they offer, and other similar marketing messages. If you are planning to start a study and want to choose a software, this many options are certainly going to make your life difficult. ## Objective Reviews To help you make an informed decision, we have put together a resource to compare all software packages. But like everything else at Avicenna, we wanted to do a thorough job, rather than just write a "Why is Avicenna better?" article. In particular, the following factors were very important to us: - **Comprehensive**: Include every feature and capability that your research may need. - **Always up-to-date**: Remain up-to-date following new softwares and new features. - **Easy to read**: You can scan through it in a few minutes, or spend hours checking details. Your choice. - **Community-driven**: Anyone can contribute to it, either by expanding the feature space or better presenting a software. - **Objective**: Put our bias towards Avicenna aside, and objectively study the pros and cons of all available packages. The result is a public GitHub repository that you can access [here](https://github.com/avicennaresearch/ema_software_comparison). This repository lists all features a software package may offer (nearly 350 features). It then categorizes these features into a hierarchy, comprising 12 categories and approximately 50 subcategories. And then for each feature, the repository documents the relevant capabilities of each software package. In the end, based on whether a given feature was fully supported, partially supported, or not supported, a score is assigned to each software package in each category and subcategory. A small Python code automatically creates a spreadsheet based on information in this repository. You can access the spreadsheet [here](https://docs.google.com/spreadsheets/d/1zRuZIJKE9mm90asM9U07MRmoJE51giFEUMJQhXZDf3Y). ![](/assets/why-avicenna-ema-software-comparison-spreadsheet.png) This way, you can check the spreadsheet to have a quick assessment of what software offers a better set of features overall, or in a certain domain. That would take you just minutes. Alternatively, you can check features that are important to you, and see how each software package supports it. You can go even further and check the GitHub repository's history to see how this assessment was made, what discussion was around it, and if you find a mistake, send a patch to correct it. ## Subjective Reviews As we studied and worked with different software packages, we formed an opinion on what are the pros and cons of each package. Being a team of software engineers, we could also sometimes read between the lines and guess why some software packages have designed certain features the way they have. We did not include these evaluations in the above spreadsheet, to keep that only focused on objective metrics. But at the same time, we know these subjective assessments are equally important, if not more so. They give us a good perspective on what are the strengths of each competitive product, and what are their weaknesses and pitfalls. In the following articles, we share this subjective analysis for each software, along with its objective comparison from the spreadsheet. We believe this provides you with a very good holistic understanding of how our work compares to our competitors. ## On The Side In addition to our comprehensive competitor analysis, both objective and subjective, we also recognize the value of using Avicenna alongside other specialized research tools like [Qualtrics](https://qualtrics.com). In the following pages, you can find articles that explain how Avicenna can work together with such tools as a complement to make your research even better. --- sidebar_position: 2 --- # Compared to ExpiWell ## First Impression: A Work-in-Progress Product Setting up a study in ExpiWell is fairly easy. There is a clear flow for researchers to define surveys, add screening questions, configure prompt schedules, and distribute the study. Then all is set and we can wait for the data to flow in. There is a clean interface and easy-to-adjust configurations. The problem starts when trying to implement a protocol with medium-level complexity, as seen in many real-world studies. Often ExpiWell is missing capabilities that are expected to be part of any EMA software. The first example is the branching and skip patterns. ExpiWell offers a very basic branching, which is not suitable for any real-world survey. There is no option to branch based on responses to other surveys or add conditions based on multiple questions. The most advanced branching is "Display a question if the response to another question in the current survey is X". For anything beyond that, you are out of luck! Another example is surveys triggering logics, called `Schedules`. They are defined as study-wide rather than only for a survey. There are only 3 options: Calendar (for absolute dates), Rolling (for relative dates), and Static (user triggered). Whichever you choose, that will be the entire study! That is a major limitation for many studies. Even within this seemingly simple Schedule framework, there are many points of confusion. The first is that it's not clear what a survey availability time window is, what a _Notification_ is, or how exactly a survey is expired. If the survey is available to the participant from the start of the time window, why is a notification sent at a later time? Or why is expiry measured relative to the notification prompt, rather than survey availability? Unfortunately, the documentation does not help much with clarifying these questions either. So, the only option is to do a trial and error using the website and the app! Things get more complicated when you include the Event Triggering feature. This feature allows you to adjust the Schedule's attributes (start time, end time, addition, removal, etc) upon a certain event. This makes it very hard to understand and debug the flow of a study. There are other minor examples as well. For example, Fitbit data collection only works when a survey is prompted, Participant Payment is done via the Audit Logs tab, or offline notifications exist but you are strongly discouraged from using it. When considering all these, the feeling is that ExpiWell is more of a work-in-progress than a mature product. Many features require considerable further development or even a complete redesign before they can be reliably used in a wide range of studies. ## Feature Category Comparison The following table compares Avicenna and ExpiWell on different categories of features:
Category Superior
Study Setup & Deployment
ExpiWell leaves many features in this category to be desired, such as audit logs, participation management, consent, or a multilingual interface. However, the features it offers, such as enrollment and screening, are well-implemented and easy to use.
Notifications
ExpiWell's notification is very basic. There is almost no customization nor any reporting and monitoring of the notifications. This is unfortunate because notifying participants is the single most important factor to increase compliance.
Participant Activities
ExpiWell's Schedule system is fairly basic and yet confusing. Their lack of any scripting makes the platform very limited. In the absence of session reporting and management features, researchers are left to guess what will be prompted to participants.
Survey
ExpiWell's Survey Editor is clean and easy to navigate. Many features are missing, but the question types that are implemented satisfy most use cases.
Interventions & Cognitive Tasks
While Avicenna's score is higher in this category, neither Avicenna nor ExpiWell offers extensive features related to cognitive tasks.
Gamification & Rewarding Tie
Neither Avicenna nor ExpiWell offers any features related to Gamification and Rewarding.
Software Security & Reliability
The main issue with ExpiWell's security is the lack of a proper permission management system. ExpiWell's permission management system only supports 3 static roles, and even those are defined at the account level. This means when you permit another colleague, they have the same level of permission across all studies of your account! Due to this major flaw, we assumed they do not provide any functionality related to roles and permissions.
Sensor Data & Wearables
ExpiWell's sensor-based data collection is limited to only GPS and Fitbit, and even then, there are surprising shortcomings, such as data collection only when survey responses are asked.
Participant app
ExpiWell's app provides basic features as seen in other EMA apps but is missing more unique features such as customizing interface, profile setup, and so on.
Data Access & Analysis
ExpiWell's reporting and visualization functionality is very limited and boils down to a static table and one option to export data.
Other Tie
ExpiWell offers a good interface for license purchase and monitoring. But to the best of our knowledge, they do not offer custom on-premise deployments.
For details, please check [the comparison spreadsheet](https://docs.google.com/spreadsheets/d/1zRuZIJKE9mm90asM9U07MRmoJE51giFEUMJQhXZDf3Y/edit#gid=499879103). --- sidebar_position: 3 --- # Compared to m-Path ## First Impression: For Research or Practice? Our main impression on m-Path is that it's not clear whether the product is designed for research or for care delivery and practice. This confusion continued throughout using m-Path. The team has done some work to differentiate these two, such as defining separate dashboards for each case, but it did not help. That's why many aspects of m-Path does not fit the workflow of a research study. For example: 1. There is no _Participant_. You enroll a _Client_. 2. There is no _Study_ for participants to enroll. Rather, _Clients_ add _Practitioner_ in their app. 3. There is no concept of research team working on a study. In fact, outside of pricing, the concept of research team and access levels are unclear. That's why in order to use m-Path in a study, you should first learn the functionality, and then map it to the research flow you are familiar with. For example, to enroll participants, you should invite them as _Client_ and then ask them to add you as a _Practitioner_. The problem becomes more pronounced because the software interface and the documentation does not follow a consistent terminology. For example terms such as _Beep_, _Notification_, _Trigger_, or _Reminder_, each may refer to different concepts in different parts of the system. These issues make the product learning curve very steep. ## More Product Planning and Design Could Help On the other hand, the team in m-Path have been actively adding features to their product. Specially for survey, cognitive tasks, and participant data feedback, the product offers a wide range of options and capabilities. But for many of these features, it feels the implementation was slapdash, lacking adequate thought and planning. A few examples we noted are: 1. Surveys have an attribute which is labeled `Required`. Intuitive assumptions is that this property makes completion of the survey mandatory for participants. But it actually means "the Internet connectivity is required to upload the responses.". 2. Some technical terms are brought to surface and passed onto researcher which for non-developer users is hard to understand. Examples are whether an item should be cached locally, or whether _Command_ item should run synchronously or asynchronously. 3. Question types in a survey start by what we all expect to be a question (text, multiple choice, date and time, slider, etc.) and evolve to cover everything the software offers, such as "_Notify Person_", "_Set Home Button_", or "_Add Applet_". At some point documentation refers to them as "_Items_", but the design remains inelegant. 4. The box to type question's content is just a small one-line box, in a screen surrounded by many other items not needed at the time of creating a survey. We assumed this is to encourage researchers to type short half-line questions. But in the examples, you see you can type full HTML content there! 5. At times, the participant may be asked to "_Install a Button_". Even after working with the software for a few days, we could not fully understand what that means, let alone participants who often spend a lot less time and attention. So the approach of rapid development has allowed the m-Path team to quickly load the software with tons of functionality, but shortly after working with the product, you wish some more product planning was done beforehand. ## Limited Server Resources Certain parts of the software are very uncommon. For example: 1. m-Path stores media files for audio and video questions in a 3rd-party server. 2. Sensor data are sent to a 3rd-party server straight from the app. 3. To include image or audio in the app, you must upload them elsewhere (e.g. a file-sharing server), and put the URL in the app. The most likely explanation is that the team has limited server resources to handle all data, and that's why they have offloaded that to another server. It both saves development time and reduces load on servers. The problem with this approach is that it introduces unnecessary security risk, which in turn makes IRB approvals and institutional security reviews more complex. Further, data validation becomes a lot harder, if not impossible, because the data is fragmented between two separate servers. ## m-Path Strength The main differentiator of m-path is its ability to feedback data to participants. You can present the participants with their past input data, either in raw format or plotted in basic charts (pie-chart or bar-chart). You can further aggregate responses to a given question over a cohort within your study, or the entire study population, and present that as an intervention to participants. The ability to do these directly from the dashboard without any coding is valuable for some researchers. Achieving this in Avicenna requires embedding an HTML in the app, and customizing the content of that page. While it is more flexible, it requires custom development, which is an obstacle for common usecases. m-Path also offers some nice features, such as the ability to share surveys and protocols between other researchers, that can foster collaboration and survey reuse in research. This is similar to the work by Dr. Kirtley and colleagues at [ESM Item Repository](https://www.esmitemrepository.com/). ## Feature Category Comparison The following table compares Avicenna and m-Path on different categories of features:
Category Superior
Study Setup & Deployment
While m-Path offers some nice ideas such as protocol and survey sharing, it lacks many features such as proper localization, audit, multi-site support, or even study management.
Notifications
m-Path offers very limited support for notifications. No support for different mediums, delivery confirmation and monitoring, event-triggered notifications, and so on.
Participant Activities Tie
m-Path's triggering logic and activity session management covers most basic cases, although not intuitively. While they fall short in easy creation and management of activity sessions, their powerful scripting (pseudo R) helps them to get a good score.
Survey
m-Path offers good control over the layout of every survey page and supports complex branching thanks to its computation item. But it leaves many features to be desired such as a proper survey editor, more survey question types (not "Add a button" question). That's before getting to more advanced features like researcher-completed surveys, or support for editting responses.
Interventions & Cognitive Tasks
m-Path offers a good set of cognitive tasks in their app. They can easily be integrated into the surveys, and there are many options to control their layout. Further, you can show different visualizations on data from an individual, a group of participants, or the full study population.
Gamification & Rewarding
m-Path offers gamification and rewards within their app. Combined with their Computation Item, this becomes a useful feature to define different garmification and rewarding flow for your study.
Software Security & Reliability
m-Path does not support defining roles, access levels, and permissions. It's even unclear how to share a study between members of a research team (partly due to thier focus on care delivery).
They do not have a proper terminology or software release updates. Also they do not support many security features as defined in HIPAA and FDA 21 CFR Part 11, although they are just good security practices.
Sensor Data & Wearables
Support for smartphone sensors is very crude and ad hoc. Participants need to install a separate app, the app requests all permissions for all sensors at once, and data is uploaded to a 3rd-party server. No wearable support is available. Also as the data is moved to a separate server, m-Path does not offer any activity triggering using sensor data or any visualization on that data.
Participant app
The participant app has some limitations such as no web-based interface or no offline support, and has some poor design decisions, such as referring to T&C and EULA of the product as Consent, causing confusion with study's consent.
Aside from these, we still found the app's user experience confusing, due to confusing nature of the system. For example when using the app as a participant, we could not figure out what is Applet? What happens when applet replaces my home screen? or why I'm being asked to set button on my home screen?
Data Access & Analysis
While m-Path supports a wide range of options to show data to participants, there is not much to do with the data in the researcher's interface other than exporting it. There is no option to see data on the dashboard. Note that sensor data and media files are stored at a 3rd-party servers, so you cannot access them through your m-Path interface anyway.
Other
m-Path offers a good interface for managing license, usage, and payment via the researcher dashboard. Also to the best of our knowledge, they do not offer branded applications and custom on-premise deployments.
For details, please check [the comparison spreadsheet](https://docs.google.com/spreadsheets/d/1zRuZIJKE9mm90asM9U07MRmoJE51giFEUMJQhXZDf3Y/edit#gid=499879103). --- sidebar_position: 4 --- # Compared to mEMA ## First Impression: Learning Curve Learning the basics of mEMA is straightforward, but it often shifts the burden of complexity onto participants or researchers. Careful attention to documentation is crucial to avoid making any kind of irreversible mistake. For instance: 1. Lacking a survey versioning feature has enforced them to duplicate text in many pages of their documentation against modifying the survey after it has been used to collect data. They constantly warn that this will break all the already collected responses. 2. Analytics code which is basically a variable name for each question should be unique, otherwise, one will overwrite the other in the responses data table. Although this code is generated based on a label you assign to each question, the system doesn’t automatically check for uniqueness, potentially causing confusion and errors during data analysis. 3. Question labels and analytics codes must be 40 characters or fewer; exceeding this limit prevents participants from uploading responses. 4. GPS permissions must be granted when the app is installed and cannot be granted later. Participants must reinstall the app to enable GPS permissions if they were not granted initially. Despite the importance of these constraints, the system does not enforce it, nor it helps the user via the user interface to prevent such scenarios, which can lead to data collection errors. ## Lack of organization mEMA manages participants by dividing them into groups rather than organizing everything under a study. While this flexibility may be advantageous, it can also complicate things. For instance, when a new participant is added to a group, group's settings such as surveys are not automatically applied to the participant. You must manually assign surveys and activities to each new participant. It's strange that you can't create a new group by yourself. Instead, you have to submit a request to the support team to create new groups for you. This is very inconvenient for such a core functionality. This can be a bottleneck in your study setup process. Since the system is not designed around studies, you need to manually assign the surveys to certain participants or groups. This can be a tedious and error-prone task, especially with a large number of participants and surveys (similar shortcoming as m-Path). ## Registration and Login To avoid storing personally identifiable information (PII), mEMA does not use usernames and passwords. Instead, participants log in using a unique code. While this enhances privacy, it prevents the creation of public studies, as each participant must be predefined and provided with their unique code. ## Outdated UI/UX Founded in 2011, mEMA’s UI/UX has seen little change over the years. Although the system is feature-rich, navigating and learning to use these features can be challenging due to their complex and poor design. For example, enabling larger image sizes in a survey requires appending “\_LARGEIMG” to the question’s analytics code. Similarly, adding “\_READ” allows participants to read text while recording audio responses. These features are easily missed without thorough documentation review. ## Empty Promises mEMA’s documentation does not always support its claims and features. For instance, their pricing page lists support for various data sources, but many, such as humidity, step count, and accelerometer, are deprecated. Several features marked as “Unique to mEMA” are, in fact, standard in many EMA systems. Examples include using images as questions/responses and Garmin integration. ## mEMA Strength mEMA has many great features when it comes to having an action based on the collected data, whether in the form of a survey or sensor data. Two standout features include: 1. The ability to send JITAI (Just-In-Time Adaptive Interventions) based on the participant's physiological data collected via their Garmin devices. You can tailor the intervention to prompt a survey to the participant in case of any significant change in their physiological data. 2. High-risk responses can be flagged and sent to the researcher in real time. This can be useful in studies that require immediate intervention in case of any high-risk response. ## Feature Category Comparison The following table compares Avicenna and mEMA on different categories of features:
Category Superior
Study Setup & Deployment
mEMA is not designed as a study-based software, so it is no wonder it lacks the basic features in this area. Additionally, mEMA lacks audit logs, consent forms, screening, televisit, etc.
Notifications
mEMA supports in-app notifications and some email notifications for high-risk responses. However, you can not customize those notifications or create your templates. Moreover, you can not view the sent notifications and their status.
Participant Activities Tie
While mEMA offers a scripting feature, its time-based triggering logic has less flexibility. The sensor-based triggering logic gives mEMA the edge. However, session management is more feature-rich and easier to use in Avicenna. Therefore, it's fair to say that there's a tie in this category.
Survey
Avicenna wins this one. mEMA has some of the basic functionality such as the common question types and general survey capabilities. However, it lacks for example researcher-responded surveys or public surveys.
Interventions & Cognitive Tasks
While Avicenna offers more features in this category, the difference between the two platform is not considerable.
Gamification & Rewarding Tie
Avicenna and mEMA both fail in this category because they lack any related features.
Software Security & Reliability
mEMA falls short in this category as it lacks a convenient way to manage roles and permissions or advanced security settings for user profiles. mEMA is not GDPR compliant, which can be a significant barrier for researchers in Europe.
Sensor Data & Wearables
mEMA only supports Garmin devices. They have deprecated lots of phone-based data sources. As a result, Avicenna is the winner here since it supports Garmin, Fitbit, Polar, and many other phone-based data sources.
Participant app
mEMA has native Android and iOS apps that can work offline, but, it does not allow participants to have multiple studies at the same time or customize the app interface. Also, there is no web app for the participants.
Data Access & Analysis
With mEMA you need to export the data and move it to other software in order to view and analyze them further as there is no proper way to filter or query the data.
Other
Both mEMA and Avicenna lack a license management system, but the on-premise deployment and API-based access make Avicenna the winner in this category.
For details, please check [the comparison spreadsheet](https://docs.google.com/spreadsheets/d/1zRuZIJKE9mm90asM9U07MRmoJE51giFEUMJQhXZDf3Y/edit#gid=499879103). --- sidebar_position: 5 --- # Compared to MetricWire ## Abandoned Old Version, Stealth New Version Our review of Metricwire has been based on their publicly available documentation, located [here](https://metricwire.atlassian.net/wiki/spaces/mwknowledgebase/overview?homepageId=557098). While the content lacks details, it provides a good understanding of the features MetricWire offers and matches their publicly available [Android](https://play.google.com/store/apps/details?id=com.metricwire.android3&hl=en_CA) and [iOS](https://apps.apple.com/ca/app/metricwire/id1117108543) apps. However, even though the documentation and the apps were publicly accessible, the content was outdated, and the last update to them was 18 months ago. Upon further research, we learned that MetricWire has abandoned this app and documentation and has switched to a new application called Catalyst, available on [Android](https://play.google.com/store/apps/details?id=com.metricwire.digitalhealth&hl=en_CA) and [iOS](https://apps.apple.com/us/app/catalyst-by-metricwire/id1585123028). All new studies are asked to use Catalyst, and the documentation is also provided to researchers privately. Therefore, our assessment is not and cannot be accurate because the details of the new application are kept in stealth. Our hypothesis is that the old MetricWire app was implemented using native tool sets for Android and iOS. While this approach provides a more reliable app, it makes development slower as everything should be implemented twice: once for Android and again for iOS. MetricWire team switched to platforms such as [Flutter](https://en.wikipedia.org/wiki/Flutter_%28software%29) or [React Native](https://en.wikipedia.org/wiki/React_Native), which helps speed up the development at the cost of reliability[^1]. Because these two approaches are incompatible, the team had to release a completely new application and deprecate the old app. But as the old app still had users, or due to uncertainty about this major change, the old app and content are not fully removed and are still kept on the Internet. That's why users can access the old app and content, and unless they pay close attention, they will not know that they are dealing with deprecated content. ## Feature Category Comparison As we do not have access to the latest documentation of MetricWire, we do not comment on how Avicenna compares to MetricWire in each feature category. However, for comparison with the old version of MetricWire please check [the comparison spreadsheet](https://docs.google.com/spreadsheets/d/1zRuZIJKE9mm90asM9U07MRmoJE51giFEUMJQhXZDf3Y/edit#gid=499879103). [^1]: Please note that this is one plausible hypothesis. The main reason could be something else or a combination of factors. --- sidebar_position: 6 --- # Compared to movisens ## First Impression: Focused on Sensors Although they say they support collecting both subjective and objective data, some clues show movisens is more focused on their sensors instead of experience sampling. For example: 1. On their Products page, movisensXS is among the last items while their sensors are presented at the top. 2. On their Documentation page, again, the Sensors and Data Analysis Software sections are before the movisensXS section. 3. They have more advanced features for analyzing and working with data from their offered sensors, but their sampling data lacks such features. You get a simple chart based on the number of completed forms and for more details, you should download data. 4. The title "movisens" seems to be based on "sensors" while "movisensXS" seems to be an addition. ## Too Many On-Request Features One of the first things you'll notice after checking their documentation is the number of features that are labeled "On request". For such features you need to contact their support team; you can't even test them using the dashboard by default. For example, they have a Visual Analog question type, but if you want to have "Image Extremes" for your VAS, you should use another question type and that's "On request". We decided not to list all such features and properties, but at the time of writing this article, based on a simple search on their documentation pages, there are at least 300 such features or properties. movisens might have a reason behind this, but as an end user, this isn't an easy way to evaluate a system before using it. Note that based on their Pricing page, it seems that on-request features don't have extra costs. ## Limited To Android When it comes to user base, the wider range you support, the better. This doesn't seem to be the case with movisens. They decided to focus on Android only, because: > Experience Sampling has lots of requirements and building a solid solution for multiple operating systems is very > difficult. The iPhone is also too restricted for research purposes. We focus on Android because cheap smartphones are > available. Android is also open source and it is sustainable. Avicenna iOS apps can be considered as counter-examples. The restrictions by Apple have meanings behind them and Avicenna tries to respect them while giving the flexibility to the participants to use whatever device they're comfortable with. On the other hand, movisens doesn't have a web app for participants but it's cheaper to maintain (if you don't want to collect sensor data) and more accessible. ## Revisiting User Experience Might Help movisens could've benefited from some improvements in their user experience. We list some of the most important and obvious items below: 1. After a study is changed, there might be problems with downloading the results of participants from older versions of the study. To come around such problems, you're able to download the data from old study versions using URL flags (or query params). This doesn't seem to be a good intuitive solution. 2. In exported results from forms, they refer to forms and triggers by their names (not IDs) which can change. Maybe that's why exporting data from older versions is unintuitive (as mentioned above). Note that they don't offer a comprehensive Audit Trail either. 3. No way to manage data through the dashboard. You can download it only. They have one page for Results which includes one simple chart. 4. Their Audio question doesn't have a UI for the recorded/recording audio. It just says "Don't close the question" when the audio is being recorded. 5. Their chat system is not real-time on the researcher's side. You should refresh the page. 6. It seems their Sampling page has some validation checks too. But you can't see the errors. It just changes the node border colors. You should guess the errors. 7. You can have mutable values (i.e. variables) based on Time and Date & Time responses, but not responses to Date questions. 8. If you change only the layout of the sampling flowchart (for example, just drag/drop a node), it'd result in a new protocol version and needs re-consent on the participant's side. 9. You only receive (chat) messages from participants if you have "write" access to the study. 10. They have a Reaction Time form item. As a best practice, they say: > Please do not configure a headline, because the Reaction Time Item is hidden for the participant. But it's not clear why such a form item has a headline in the first place. 11. They don't have any email verification after signing up. But you can, for example, reset your password. ## Hard Time With Maintenance? They say app updates may break your study in the field. So, they suggest disabling auto updates in Android. On the other hand, you can change the library version for your study, but they recommend only doing so when their support tells you to. These two specific behaviors don't seem to be aligned with continuous updates/improvements which is a best practice in software development. In Avicenna, we have weekly updates to make sure our users have the most fluent experience while benefiting from new features. Also, if you check their Recent Changes and News, the frequency of their updates is low and the last update might be months ago. ## Not Focusing On Personal Devices It seems their main focus is on devices researchers give to participants. Some possible clues: 1. They only support Android devices. 2. They have a section on their documentation called "Prepare for a Lost or Stolen Device". 3. They mentioned some requirements to "Configure a study smartphone". 4. Also, the "Play Video" question needs the video to be in the smartphone's SD Card. 5. The "Record Audio" feature which is part of their sampling, records the audio of the microphone for the specified duration and stores it on the smartphone's SD card. 6. They offer a "Log Node Status and Variables" (which is an on-request feature of course) for the Study Running sampling node. If that property is enabled, node status changes will be logged into a Unisens file format under `/sdcard/movisensXS/logs/`. They haven't mentioned how those logs will be accessible to the researchers though. ## Registration Flow: A Double-Edged Sword movisens participants only need a QR code from the researchers and they can start participating in no time. This has some pros and cons. Let's start with the pros: 1. It's more convenient for the participant. 2. Less footprint. It's like you came in, did the job, finished the study, and no one knows who you are (except probably some of your metadata like IP). 3. More privacy. Participants don't need to use any authentication with email address, phone number, username, and password. That being said these cons might come to mind: 1. As a researcher, you can't use email and SMS notifications to inform participants. 2. In some research studies, knowing about the PII of participants is necessary. movisens doesn't offer that and it seems they even try to prevent it. In their FAQ page, they say: > movisens does not know the identity of the participant. All participants get a pseudonym. In the study no personal > data is allowed to be collected that allows to identify the participant (e.g. name). ## movisens Strength movisens' Sampling page is very intuitive and easy to use. Sampling is done by moving around some flowchart nodes, connecting them with some logical restrictions, and adjusting the properties in each node. With this user interface, researchers also have a complete overview of what should happen for participants. We haven't tested this for bigger studies with very complex sampling protocols. Although we know that big/complex flowcharts are not easy to traverse and digest. On the other hand, for movisens Forms, you can only define internal protocol and branchings. But it's the sampling that makes those forms available for the participants. So, we see this separation (which is not 100% perfect since it has internal branchings in forms) as a nice thing to have. ## Feature Category Comparison The following table compares Avicenna and movisens on different categories of features:
Category Superior
Study Setup & Deployment
movisens lacks features in many areas like localized study content, eligibility screening, enrollment available to the general public, participant management, Televisit (Chat), and multi-site studies. Also, they don't have any Audit Trail which is one of the most important items in an EMA system toolbox.
Notifications
movisens only supports in-app notifications. They don't support other mediums like email or SMS. Also, you can't define templates for notifications. And, you can't monitor the notifications and their statuses, especially notifications in the future.
Participant Activities
While movisens offers more features on scripting, variables, and triggering logics, they lack more complex features for managing activities and sessions. That's why Avicenna ranks a bit higher in this category.
Survey
movisens has some good features like the Likert questions or section-based layout for participants. But Avicenna is more flexible and feature-rich in general capabilities of surveys, question types and their properties, eCRFs, public surveys, and analyzing responses.
Interventions & Cognitive Tasks
Although neither movisens nor Avicenna is feature-rich in this category, Avicenna offers more cognitive tasks like Stroop and Matrix Reasoning.
Gamification & Rewarding
In this category, movisens is the winner since Avicenna doesn't offer any feature. Note that movisens only supports one feature from this category.
Software Security & Reliability
Here, Avicenna seems to have valued security more than movisens. Avicenna supports almost three times more features including flexible study roles and permissions, complying with guidelines and regulations, and following software development's best practices.
Sensor Data & Wearables
While movisens offers their own sensors, we didn't include them in the comparison since they're not identified as standard ways other EMA systems should use to collect sensor data. Considering this statement, Avicenna supports more data sources including mobile sensors and wearables which are more accessible to participants.
Participant app
movisens allows participants to configure their apps a bit, but it lacks some bigger features like supporting iOS and web apps, dropout surveys, and participating in multiple studies in parallel.
Data Access & Analysis
Avicenna wins this one. It has a comprehensive data filtering system researchers can apply to almost all types of data. Also, Avicenna uses Kibana which is a powerful tool to visualize data with different types of charts.
Other Tie
movisens offers a good interface for monitoring the quota. But to the best of our knowledge, they do not offer custom on-premise deployments.
For details, please check [the comparison spreadsheet](https://docs.google.com/spreadsheets/d/1zRuZIJKE9mm90asM9U07MRmoJE51giFEUMJQhXZDf3Y/edit#gid=499879103). --- sidebar_position: 7 --- # Alongside Qualtrics This article explains how you can use Avicenna alongside [Qualtrics](https://qualtrics.com) to broaden your study's possibilities. Qualtrics is an experience management (XM) system that seems to be focused on Customer and Employee experience more than EMA and experience sampling research methodology. However, the platform is versatile enough to meet most survey-based needs. If you're familiar with Qualtrics, you know they excel in: - **Surveys:** Their survey tools are comprehensive and feature-rich. They offer a wide range of question types, logic branching, anonymous/public surveys, and customization options that can handle even the most complex survey designs. - **Data & Analysis:** Qualtrics offers powerful tools for reviewing and analyzing data. They have various reporting widgets, charts, and AI-driven analysis features like auto-generated reports and trend identification. Their real-time analytics help in making informed decisions quickly. If these features are a must for your study, Qualtrics might be the primary platform you use. On the other hand, they offer many ways to bring data into their platform, including creating separate data projects, importing video and audio projects, importing survey responses, and using supplemental data sources. Qualtrics also has integrations with other software like Chat Messaging apps, but that's beyond the scope of this article. In conjunction with Qualtrics, you can use Avicenna for features that are missing or hard to achieve in Qualtrics. Below, we outline how Avicenna can complement Qualtrics. ## Sensor Data Qualtrics is great in survey-based data collection but lacks sensor integrations. Avicenna, however, has an extensive range of [data sources](../reference/data-sources/) that you can use, from wearables (e.g., Polar, WHOOP, and Fitbit) to mobile app sensors (e.g., GPS, Screen State, and Gravity). You can use Avicenna mobile apps or integrate with external wearables to collect sensor data and then import this data into Qualtrics for deeper analysis and custom sampling over surveys. For example, this gives you the ability to correlate survey results with physiological data, providing a richer context for your research. ## Cognitive Tasks Qualtrics does not support cognitive tasks, which are critical for certain types of research. While you might be able to simulate such tasks partially and probably with too many limitations using Qualtrics surveys, Avicenna offers a range of cognitive tasks like Stroop, Time-Use, and Matrix Reasoning (IQ Test) each specially designed based on its purpose. You can use Avicenna to administer these cognitive tasks and then import the collected data into Qualtrics. This allows you to integrate cognitive performance data with other survey responses, providing a more comprehensive view of your participants. ## Offline Android and iOS Apps Qualtrics does offer an offline mobile app, but it is mainly geared towards researchers collecting face-to-face responses. [Avicenna’s participant mobile apps](../reference/study-setup-and-deployment/enrollment.md#avicenna-participant-app) are offline-first, enabling survey responses to be collected without an internet connection, which is crucial in regions with poor connectivity or for field studies. If offline data collection is essential for your study, you can use Avicenna for data collection and then import it into Qualtrics for further analysis. ## Video and Audio Responses You can use Qualtrics to collect video and audio responses from participants (whether as a file or a recording) using their surveys. But if, for any reason, you decided to use Avicenna surveys for that purpose, you might still want to use Qualtrics Imported Video and Audio Projects for deeper analysis of such responses. When analyzing your imported responses in Qualtrics, you can review the response's auto-generated transcript and sentiment, assign tags based on the response content, and organize responses into highlight reels. ## Final Words We are constantly improving our platform to meet your needs and bridge gaps between us and other tools. The robust survey and data analysis features of Qualtrics are areas we target in our roadmap, aiming for Avicenna to be the only platform you need for your studies. To achieve this, we welcome feedback and ideas. Don't hesitate to reach out to us at support@avicennaresearch.com or [our Forum](https://forum.avicennaresearch.com). Check our [weekly](https://forum.avicennaresearch.com/c/release-notes/6) or [monthly](https://avicennaresearch.com/blog/tag/platform-updates/) release notes to see our recent developments, plans, and evolution. --- sidebar_position: 3 --- import DownloadButton from '@site/src/components/download-button'; # Ask AI You want to learn about Avicenna Research or find answers to specific questions about the platform. While our documentation (the current website) includes a search feature, we suggest a more intuitive way to get personalized explanations without browsing many pages. ## How 1. **Download the Avicenna Learn file.** This [markdown file](https://en.wikipedia.org/wiki/Markdown) contains our entire documentation and is automatically updated with every change. 2. **Go to [Google AI Studio](https://aistudio.google.com/).** Log in with your Google account if needed. The **Chat** tab should open by default. ![Google AI Studio's Chat page](/assets/google-ai-studio-chat-page.png) Note: These instructions work with most AI tools, not just Google AI Studio. 3. **Select the documentation file** by clicking on the "Insert" button. Wait for the file to be uploaded and processed. !["Insert" button in Google AI Studio](/assets/google-ai-studio-insert-button.png) 4. **Ask your question about Avicenna.** For example: - "How can I make a multi-arm study in Avicenna Research?" - "What types of activities can I create in Avicenna?" - "How do I set up Geofencing in my study?" ![Asking a question in Google AI Studio](/assets/google-ai-studio-prompt-with-attachment.png) 5. **Click on the "Run" button.** ![AI is thinking](/assets/google-ai-studio-thinking.png) 6. **Review your personalized answer.** ![AI-generated response](/assets/google-ai-studio-response.png) 7. **Save your prompt for future use.** Name your chat something like "Avicenna Research Assistant" or "Avicenna Learn". !["Save" button in Google AI Studio](/assets/google-ai-studio-save-chat.png) You can also **enable auto-saving** for all your chats using the `Settings` > `Autosave` option. !["Autosave" option in Google AI Studio](/assets/google-ai-studio-autosave.png) ## Best Practices - **Be specific with your questions** to get the most relevant answers. - **Ask follow-up questions** to dive deeper into topics. The AI remembers your conversation context. - **Download the latest documentation file** periodically for the most up-to-date information. - Google AI Studio (using Gemini 2.5 Pro) and other AI tools have **usage limitations for free accounts**, but these should be sufficient for most learning purposes. --- sidebar_position: 1 --- # Terminology ## Activity An interaction or task performed by participants in your study, such as completing surveys, engaging in cognitive tasks, or logging daily diaries. The types of activities are predefined by Avicenna, but their content can be modified by researchers to meet the specific goals of their study. See [Activity](./activities/README.md). ## Audit Logs The logs recorded by Avicenna from the participant's or researcher's interactions with the study, providing evidence of user actions and events for tracking and analysis. See [Audit Trail](./study-setup-and-deployment/audit-trail.md). ## Background App Refers to a state of the Avicenna app for Android or iOS, when it's not visible on the phone's screen, but it is operational behind the scenes. The app in this state can still collect sensor data or prompt notifications. This is the opposite of the [Foreground App](#foreground-app) state. ## Blocked Session Avicenna app can only have one active session for a given activity at any given time. For example, if a study contains a survey for a health check that is prompted to participants once a day, before the session for the new day is prompted, the session for the previous day should be concluded. If the session for the last day is still active and awaiting the participant's response, the new session will be marked as _Blocked_. See [Blocked Sessions](./activities/activity-sessions.md#blocked-sessions). ## Canceled Session If a participant explicitly indicates they do not want to continue responding to a given session from a given activity, the session will be marked as _Canceled_. Any responses provided by the respondents up to the time they cancel the survey will be uploaded and will be available in your study. See [Session Statuses](./activities/activity-sessions.md#session-statuses). ## Closed Study A state of a study, in which no new participant can join the study. In this state, currently enrolled participants can continue their participation without any interruption. See [Enrollment Types](./study-setup-and-deployment/enrollment.md#enrollment-types). ## Cognitive Task A type of activity where the participant is asked to perform a particular cognitive task. Similar to surveys, cognitive tasks can be presented once or multiple times to each participant. See [Cognitive Tasks](../category/cognitive-tasks). ## Completed Session A session that is completed by the participant or researcher. For example, in the case of survey activities, a survey session is completed when the participant or researcher responds to all presented questions and presses the _Submit_ button. See [Session Statuses](./activities/activity-sessions.md#session-statuses). ## Consent Material The content outlining the study's purpose, procedures, and participant rights. Must be reviewed and agreed upon by participants before joining, ensuring ethical standards are met. Participants can always access this via the Avicenna app. See [Create a New Study](./study-setup-and-deployment/create-a-new-study). ## Criteria A conditional expression or a formula that instructs Avicenna whether an action has to happen or not. If a component in your study contains a criteria, every time Avicenna wants to execute that component, it first evaluates the criteria. It only proceeds with the execution if the criteria is _True_. See [Criteria](./activities/criteria.md). ## Data Source A type of data that is automatically collected from participants without their involvement. Examples include sensor-based data such as motion data via accelerometer, location via GPS, or heart rate via wearables. It also can include digital footprints such as screen time or app usage. See [Data Sources](../reference/data-sources/README.md). ## Device A device that is used by a participant to participate in a study. It can be an Android phone or tablet, an iOS phone or tablet, or a web browser. Each device is uniquely identified via a device ID. See [Participation](./study-setup-and-deployment/participation). ## Device Operation Percentage The percentage of the time that the Avicenna app was running, in the [foreground](#foreground-app) or the [background](#background-app), collecting sensor data. See [Participation](./study-setup-and-deployment/participation). ## Draft Changes Draft changes are the changes that are not published yet, and therefore cannot be viewed by the participants. Participants always only have access to the latest published version of a survey activity. See [Publish Surveys](./surveys/README.md#publish-surveys). ## Dropout Survey A type of activity to be prompted immediately after the participant decides to withdraw from the study, and before the withdrawal is completed. See [Dropout Survey](./study-setup-and-deployment/study-dropout.md#dropout-survey). ## Eligibility Survey A type of activity to be prompted immediately after the participant decides to join the study. This survey uses criteria to decide whether the participant should be included in the study or not. See [Eligibility ‌Survey](./study-setup-and-deployment/eligibility-screening.md#eligibility-survey). ## Enrolment Status Indicates whether a study is open to new participants, closed, or invite-only. See [Enrollment Types](./study-setup-and-deployment/enrollment.md#enrollment-types). ## Expired Session Sessions are marked as _Expired_ when not completed within the set timeframe. Any responses provided up to the expiration time will be uploaded and will be available in your study. See [Expired Sessions and Expiry Time](./activities/activity-sessions.md#expired-sessions-and-expiry-time). ## Expiry Duration The duration allocated for completing a session, after which it becomes expired. See [Expired Sessions and Expiry Time](./activities/activity-sessions.md#expired-sessions-and-expiry-time). ## Foreground App Refers to a state of the Avicenna app, either Android or iOS, in which the participant is interacting with it on the phone’s screen. This is the opposite of the [Background App](#background-app) state. ## In Progress Session This status indicates the session has started by the participant and some questions have already been responded to, but it's not completed yet. See [Session Statuses](./activities/activity-sessions.md#session-statuses). ## Invite-Only Study A state of a study, in which participants can join the study only if they are invited to the study by the researcher. The invitations are based on the email addresses of the prospective participants which are used for invitation. See [Enrollment Types](./study-setup-and-deployment/enrollment.md#enrollment-types). ## Join Time Indicates the date and time when a participant joins the study. This does not get updated if the participant rejoins the study after dropping out or getting dropped out by the researcher. Also, the join time does not necessarily mean the start of data collection. The data collection starts at the [Participation Start Time](#participation-period). ## Notification An alerting message sent to a participant or a researcher. A notification is created either from a template or manually sent from the _Notification_ page on the researcher dashboard. When a given event occurs for which a notification template is defined, Avicenna creates a notification based on that template, fills all placeholders (e.g. with the name of the recipient), and sends the notification through the specified mediums. The sent notification will be saved for reference. See [Notifications](./study-setup-and-deployment/notifications.md). ## Notification Medium A medium through which notifications are sent, including email, SMS, and in-app messages. See [Notifications](./study-setup-and-deployment/notifications.md). ## Notification Template A template for a notification, that specifies the recipient of the notification, the event that should trigger the notification, the offset of the notification based on the occurrence of the event, the criteria under which the notification should be prompted, the mediums through which the notification should be sent, and the content of the notification for each medium. See [Notification Template](./study-setup-and-deployment/notifications.md#notification-templates). ## Participant Participants, or respondents, are individuals who have consented to join your study to perform the tasks you have asked them and provide the data your study collects throughout the participation period. Participants can use the Avicenna app on their Android, iPhone, or browser to participate in a study, but they cannot access the researcher dashboard, make changes to the study configuration, or see the data from other participants. ## Participant App Version Each release on participant mobile apps has a unique version which is used to identify that specific release. ## Participation Duration This refers to the number of days that participants will be part of the study and provide data. See [Participation Period](./study-setup-and-deployment/participation-period.md). ## Participation Period The Participation Period comprises from the Participation Start Time to the Participation End Time. Participation Start Time is the first day on which data collection from participants starts. Note that participants may register in the study earlier, but Avicenna does not start data collection until the Participation Start Time is reached. If a participant joins the study after the Participation Start Time, data collection starts immediately. Similarly, Participation End Time refers to the end of data collection from participants. No new participant can join after this date. Also, data collection will stop from all participants on this date. See [Participation Period](./study-setup-and-deployment/participation-period.md). ## Proximity Triggering Logic A triggering logic that prompts a given activity when the Avicenna app detects the proximity between the participant and another physical object, e.g. another participant, a certain location, or a bike. Such detection happens using Bluetooth Beacon data; therefore, this triggering logic is applicable only if the study contains the Bluetooth Beacon data source. See [Proximity Triggering Logic](./activities/triggering-logics.md#proximity-tl). ## Public Study A state of a study, in which anyone can join the study, whether they hold an invitation or not. See [Enrollment Types](./study-setup-and-deployment/enrollment.md#enrollment-types). ## Registration Code A code participants should enter to find your study within Avicenna and enroll in it. Participants can enroll in your study in different ways, including a URL, QR code, or registration code. See [Study Enrollment](./study-setup-and-deployment/enrollment.md#study-enrollment). ## Researcher Researchers are study staff members who have access to the study settings and participants' data through the Researcher Dashboard. They can design the study, configure different components in Avicenna, screen and enroll participants, monitor adherence, in addition to analyze study data. Researchers cannot participate in a study as a participant with a researcher account. They also cannot log in to the Avicenna app as the app is intended for the participants only. ## Researcher-Defined Session Researcher-defined sessions refer to the manually created and scheduled sessions initiated by researchers. See [Creating a Researcher-Defined Session](./activities/activity-sessions#creating-a-session). ## Session When an activity such as a survey is triggered to a participant, Avicenna will create a _Session_ for it. This session will hold the information about the triggered activity, as well as the metadata and the responses provided by the participants. For example, every time a survey is completed by a participant, the data are stored as a survey session. Similarly, every time a participant completes a cognitive task, the data is stored as a cognitive task session. See [Activity Sessions](./activities/activity-sessions.md). ## Study Study is the main building block of a research within Avicenna. Each _Study_ represents a research project. It defines the study protocol, enrollment strategy, surveys, cognitive tasks, data collection scheme, and other settings. It also contains all data collected from the participants. Studies are independent components within Avicenna, and they cannot share data with other studies, even if they all are created by the same researcher. See [Create a New Study](./study-setup-and-deployment/create-a-new-study). ## Study ID A unique identifier for the study within the Avicenna platform. Participants can find and join the study by entering the ID of the study. See [Study Enrollment](./study-setup-and-deployment/enrollment.md#study-enrollment). ## Study URL A URL participants can use to enroll in the study. See [Study Enrollment](./study-setup-and-deployment/enrollment.md#study-enrollment). ## Survey A type of activity by which the participants are asked to respond to a set of questions. Similar to cognitive tasks, presenting a survey to each participant is possible either once or multiple times. Each time a survey is presented to a participant, the gathered metadata and responses are stored in a survey session. See [Surveys](./surveys/README.md). ## Survey Definition File A Survey Definition File is a file that contains all the structure, content, and logic for a Survey. It can be used as a base for creating different similar Surveys. Such file typically includes information such as metadata, questions, possible answers, and TLs. See [Survey Versions, Import and Export](./surveys/#versions-import-and-export). ## Time Triggering Logic A triggering logic that determines when an activity should be prompted to the participant based on a specified time-table. A Time Triggering Logic always contains an initial time. In detail, this is the time when the activity is prompted to the participants for the first time. It may also have a repeating schedule, which if set, the activity will be prompted multiple times based on the repetition schedule. See [Time Triggering Logic](./activities/triggering-logics.md#time-tl). ## Triggering Logic A logic that specifies when an activity should be prompted to the participant. This can be based on time, user's actions, or sensors' data. See [Triggering Logics](./activities/triggering-logics.md). ## Unanswered Session This status indicates Avicenna does not know the status of the session yet. The unanswered sessions are generally divided into two groups: those whose scheduled time has not arrived yet, and those whose scheduled time has already passed. If the scheduled time of a session has not arrived yet, this means the session is not prompted yet. When the scheduled time arrives, Avicenna evaluates the criteria of the session (if any) and prompts it if the criteria is true. If the criteria is not true, the session will be skipped and it will be treated as a non-existent session. If the scheduled time of the session has already arrived, but the status is still Unanswered, it means the Avicenna server has not received the status from the device yet. Because the Avicenna apps for Android and iOS work offline, if the participant does not have an Internet connection at the time of completing a survey, the status of the session is not updated immediately after its scheduled time. Hence, the scheduled time may pass, and the session may still be shown as Unanswered. Avicenna server updates the status immediately after it receives it from the participant's device. See [Session Statuses](./activities/activity-sessions.md#session-statuses). ## Unknown Session Please refer to [Unanswered Session](#unanswered-session). ## Upcoming Session Please refer to [Unanswered Session](#unanswered-session). ## User ID The unique ID of the user in Avicenna. Each user, either the researcher or participant, has a unique ID in Avicenna. This ID enables us to refer to this user across the system. Often in the documentation the term `Participant ID` refers to the User ID of the participant, and `Researcher ID` refers to the User ID of a researcher. ## User Triggering Logic A triggering logic that instructs Avicenna to give the option of starting an activity and repeating it as many times as desired to the participants. In detail, Avicenna adds a button to the participant's homepage on the app, then participants can launch an activity via that button at any time. See [User Triggering Logic](./activities/triggering-logics.md#user-tl). --- sidebar_position: 1 --- # Profile Settings This section will help you through some basic settings in the researcher dashboard, particularly the Two-Factor Authentication and Password Change features. By tapping on the _Profile_ button at the top right corner of the researcher dashboard, you will have access to four features: _Personal Information_, _Security_, _Notification Settings_, and _Log Out_. ## Personal Information Assuming [your email address has already been verified](../../getting-started/create-a-researcher-account.md#how-to-create-a-researcher-account), the next step is to add your phone number. This step is mandatory to enable the _Two-Factor Authentication_ or if you want to receive SMS notifications. To do this, click the `+` button, verify your password, and enter the phone number after selecting your country. ![Adding phone number](/assets/profile-settings-adding-phone-number.png) This will be followed by receiving a verification code as a text message. ![Phone verification code](/assets/profile-settings-phone-number-verification-code-sms.png) Then enter the code in the specified field as soon as you get it. When you are done, you will see a message in the bottom-left corner of the page indicating that your phone number has been verified successfully. You can also see a green message under the _Phone Number_ section informing you that the phone number is verified. ![Verified phone number](/assets/profile-settings-verified-phone-number.png) ## Security The second setting at your disposal in _Profile Settings_ is _Security_. Selecting that will offer you some additional features we explain below. ![Security tab](/assets/profile-settings-security.png) ### Two-Factor Authentication By enabling the _Two-Factor Authentication_ feature, Avicenna provides an extra layer of security to ensure you are the only person with access to your researcher dashboard. Enabling this feature allows Avicenna to confirm your identity via text message whenever you log in to your account. If you haven't specified a phone number for your account or your phone number isn't verified, when you try to enable this feature, you will be prompted with the phone number addition/verification steps first. Immediately after enabling _Two-Factor Authentication_, a message appears at the bottom of the page that notifies you of your profile update. After that, every time you attempt to log in, a security code will be sent to your phone, which you need to use to access your researcher dashboard. ### Auto-Logout Avicenna also provides _Auto-Logout_. By enabling this feature, Avicenna will automatically log you out after 20 minutes of inactivity. This is an additional security measure to ensure that your account is secure even if you forget to log out. This feature is disabled by default. ### Password Expiry Enabling _Password Expiry_ will require you to change your password every six months. This enhances the security of your account by ensuring that your password is regularly updated. This feature is disabled by default. ### Password Change The _Password Change_ feature in the Security settings allows you to change the password as you see fit. After tapping _Password Change_, a page will be displayed where you can create a new password. Note that a new password will only be possible after confirming the current one. If you have difficulty remembering your password, click on _Forgot Password_. This will show you a dialog indicating that you will be logged out and redirected to another page where you can reset the password. Confirm the decision by pressing the _Go_ button. Once on that page, enter the email address you initially used to create the researcher account, and click on _Reset Password_. ![Reset your password](/assets/profile-settings-enter-email-forgot-password.png) Afterward, Avicenna will send you an email with instructions on how to set a new password. ![Request to reset your password](/assets/profile-settings-password-reset-request.png) Open your email account and tap on the link sent by Avicenna. ![Instructions to reset your password](/assets/profile-settings-password-reset-email-instruction.png) When the new password is selected and confirmed, press _Change My Password_, and you will be taken back to your researcher dashboard. ![Enter your new password](/assets/profile-settings-reset-password.png) :::note You can not use the last two passwords you have previously set. Also, you will be logged out of your other devices, if any, after changing your password. These are essential to ensure the security of your account in case of a password leak. ::: ## Notification Settings In this tab, you can customize and personalize your notifications. You can choose whether they have to be sent via SMS or Email. For more information, check the [Notifications](notifications.md#notification-settings-in-avicenna) page. --- sidebar_position: 2 --- # Create a New Study The first step of using Avicenna is to create a [study](../terminology.md#study). Studies are the main building blocks of Avicenna, as they represent your entire research project; you cannot use Avicenna for your research project without creating one study. ## Your Studies Avicenna allows you to be part of multiple studies as a researcher or own multiple studies as an owner. To see an overview of all your studies, you can go to the `My Studies` page in your dashboard. ![My Studies page in Avicenna researcher dashboard](/assets/researcher-dashboard-my-studies.png) On that page, you can open a study by clicking on its row. You can also create new studies in two ways which we'll cover below. ### Creating a New Study From Scratch You can start a new study from scratch by clicking on the `Create Study` button on the `My Studies` page. This will open the `Create a New Study` dialog. Click on `Let's Go` to proceed. On the next page, you can enter the initial information about your study. Below, we will walk you through these steps. At every step, make sure you enter a valid response. When you do so, the checkmark next to the box will be enabled. You can then press the checkmark button, or the Enter key on your keyboard to go to the next field. You can also move between completed steps by clicking on their titles. ![Create a New Study form in the Researcher Dashboard](/assets/create-a-new-study-form-in-researcher-dashboard.png) #### Study Name The first step is to provide a name for your study. The name should be short, memorable, and concise. It will be used in both the researcher dashboard and the participant apps to refer to this study. #### Organization Name Next, specify the name of the organization conducting this study, which defaults to your affiliated institution but can be changed if preferred. #### Consent Materials Next, you should enter the content of the participant consent form for your study. This is typically the content that is approved by your institution's review board as part of your study's ethics review board application. This content is shown to participants during registration before they join your study. Participants are expected to read and accept this content before joining the study. Specifically, you need to ensure your consent form covers the following: - What is the purpose of the study? - What potential risks or benefits might participants experience? - How will participant data be handled and who will have access to the data? - How can participants contact the research team if needed? - What are the steps for withdrawal from the study? If you plan to meet with each participant in person and ask them to sign a paper consent form, then the content written here should be primarily informative. In this case, you can just include the information you want participants to access easily. If you aren't collecting signed paper consent forms from participants, you should include the full consent form materials here and inform participants that by registering in the study, they are providing implicit consent. You can format your content using the available controls at the top of the input area. #### Participation Period At this stage, you determine how Avicenna should calculate the participation period by setting the start and end dates/times. As participants join your study, Avicenna automatically schedules the beginning and end of their participation. We explain this in more detail in the [Participation Period](participation-period.md). #### Participation Duration As the final step of creating a new study, you need to determine how many days each participant will take part in the study. #### Finalize After adjusting the participation timeline in the last steps, you can click on the `Start` button to create your study. This might take a few seconds, during which Avicenna will set up a database for your study. After this, you will be redirected to your study's homepage ([`Basics` page](create-a-new-study.md#basics-page)) in your researcher dashboard. ### Duplicating a Study While [creating a study from scratch](#creating-a-new-study-from-scratch) is what you probably need most of the time, Avicenna offers an alternative method to create studies quickly and easily. If you're the owner of a study and need to create a similar study protocol/schema (not the participants or their data) in a new study, you can duplicate the existing one. To do this, go to the `My Studies` page, click on the 3-dot menu next to the study, and choose `Duplicate`. After confirming the action, Avicenna will begin duplicating the study in the background. Upon completion or if the process fails for any reason, you'll receive an email about the result. These parts of your study will be duplicated: - [Basic settings](#basics-page) - [Localizations and translations](localization.md) - [Sites](multi-site-studies.md) - [Activities](../activities/) (the last [version](../surveys/#versions-import-and-export) only) - [Data sources](../data-sources/README.md) excluding [beacons mapping](../data-sources/from-smartphone/contact-network.md#beacon-mapping-page) - [Notification templates](notifications.md#notification-templates) and their links to the activities - [Researchers, roles, and permissions](roles-and-permissions.md) Also, all references to survey questions in [criteria](../activities/criteria.md) and [question placeholders](../surveys/questions.md#placeholders) will be updated based on the new duplicated survey IDs. :::note The new study will have a trial license. Similarly, some configurations like [SMS](notifications.md) and [chat (televisit)](televisit.md) will not be copied to the new study. Please contact us at support@avicennaresearch.com if you need to change those. ::: ## Basics Page The `Basics` page displays a few basic configurations for your study and allows you to modify them as needed: ![Basics page for a newly created study in Avicenna](/assets/avicenna-new-study-basics-page.png) On this page, you can view your study's ID, its name, organization name, consent materials, and participation timeline you configured during study creation. ### Study ID Avicenna assigns a unique ID to each study, helping you to distinguish it from other studies on the Avicenna platform. For example, in the shown image above, ID 1302 is assigned to our demo study. You must share this study ID with your participants depending on your preferred enrollment method. You can read more about this in the [Enrollment](enrollment.md) section. ### Study Background The `Study Background` option allows you to customize the appearance and feel of the Avicenna app and website for your study. The selected image will appear as the background in your study on the participant apps and [registration pages](enrollment.md#using-registration-url). Below is an example of a customized background image: | | | | | :--------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------: | | ![The home screen of a study with a custom background image on an Android device](/assets/avicenna-branding-home-screen-android-resized-1.png) | ![The home screen of a study with a custom background image on an iPhone device](/assets/avicenna-branding-home-screen-ios-resized-1.png) | ![The home screen of a study with a custom background image on Avicenna website](/assets/avicenna-branding-home-screen-web-resized-1.png) | To change your study background, go to the `Basics` page, click the `Edit` button in the top-right of the _Study Background_ section. This will open a dialog where you can select a background image. An ideal image aspect ratio is 9:16 (a portrait aspect ratio common among smartphones), such as 720 x 1280. ![Study Background dialog in Avicenna](/assets/avicenna-modify-study-background-dialog.png) --- sidebar_position: 3 --- # Participation Period When a participant joins your study, Avicenna automatically calculates their participation start and end times. This represents the period during which you can present surveys and experience sampling to your participants, ask them to complete a cognitive task, or collect sensor data. Participants can always check this period to see how far along they are in their participation using the Avicenna app. Setting this period correctly is very important because Avicenna does not perform any data collection outside this time window. The participation period does not have to be identical for all participants. You can customize start/end times per participant or a bunch of participants. It's common in a study, that each participant has an individual participation period individually. When setting up your study, you can define how this period should be calculated for each new participant. This can be done by adjusting three values, as described below. **Participation Start Time** This refers to the time you expect the participants to start. If you mark the _Open_ checkbox, the participation starts as soon as the participant joins your study. If you set this to a specific date, the participation starts either on the date you specified or at the time a participant joins the study, whichever comes last. **Participation End Time** This refers to the time you expect the participants to end. If you mark the _Open_ checkbox, the participation continues indefinitely. If you set this to a specific date, the participation ends for all participants on this specific date. In this case, new participants cannot join after the specified date. **Participation Duration** This refers to the number of days you expect the participants to be part of the study. This value should be greater than or equal to 1, and cannot have decimal points. Participation duration is interpreted differently depending on the values assigned to the participation start time and end time. You can either set this to a specific number of days or mark it as _From start to end_ using its checkbox. ## Different Settings for Participation Period For each of the three values we defined above, you can either set them or check their checkboxes. This gives you eight different ways by which you can adjust your study's participation period. In this section, we explain them one by one and provide an example for each. ### Marking All Checkboxes If you mark all these checkboxes, it means participants will start their participation as soon as they join the study, and will remain in the study indefinitely. **Examples:** | Participant Join Date | Participation Start | Participation End | | --------------------- | --------------------- | ----------------- | | Jun. 5th, 2020 10:15 | Jun. 5th, 2020 10:15 | Never | | Aug. 12th, 2020 19:15 | Aug. 12th, 2020 19:15 | Never | ### Setting Start, Marking End and Duration Checkboxes In this case, if participants join before the specified start time, their participation will not start until the start time. If the participants join after the study's start time, since the specified start time has already passed, their participation starts at the same time they have joined the study. The participation continues indefinitely, as no end time or duration is specified. **Examples:** Assume that the _Participation Start Time_ is set to Nov. 15th, 2020, 10:00. | Participant Join Date | Participation Start | Participation End | | --------------------- | ---------------------- | ----------------- | | Jun. 5th, 2020 10:15 | Nov. 15th, 2020, 10:00 | Never | | Aug. 12th, 2020 19:15 | Nov. 15th, 2020, 10:00 | Never | | Nov. 15th, 2020 09:00 | Nov. 15th, 2020, 10:00 | Never | | Nov. 20th, 2020 11:45 | Nov. 20th, 2020 11:45 | Never | ### Setting End, Marking Start and Duration Checkboxes In this case, the participation starts as soon as the participant joins the study. The participation continues until the specified end time. Therefore, each participant will have a different participation duration, depending on when they joined the study. In this scenario, participants cannot join the study after the specified end time. If they try to do so, they will see a message saying that the study has already finished. **Examples:** Assume the _Participation End Time_ is set to Nov. 15th, 2020, 23:00. | Participant Join Date | Participation Start | Participation End | | --------------------- | ----------------------------- | ----------------------------- | | Jun. 5th, 2020 10:15 | Jun. 5th, 2020 10:15 | Nov. 15th, 2020, 23:00 | | Aug. 12th, 2020 19:15 | Aug. 12th, 2020 19:15 | Nov. 15th, 2020, 23:00 | | Nov. 15th, 2020 09:00 | Nov. 15th, 2020 09:00 | Nov. 15th, 2020, 23:00 | | Nov. 20th, 2020 11:45 | N/A (participant cannot join) | N/A (participant cannot join) | ### Setting Duration, Marking Start and End Checkboxes In this case, the participation starts as soon as the participant joins the study. The participation continues for the number of days specified by the _Duration_. **Examples:** Assume the _Duration_ is set to 2 weeks (14 days). | Participant Join Date | Participation Start | Participation End | | --------------------- | --------------------- | --------------------- | | Jun. 5th, 2020 10:15 | Jun. 5th, 2020 10:15 | Jun. 19th, 2020 10:15 | | Aug. 12th, 2020 19:15 | Aug. 12th, 2020 19:15 | Aug. 26th, 2020 19:15 | ### Setting Start and End, Marking Duration Checkbox In this case, if participants join the study before the specified start time, their participation does not start until the start time. If participants join after the start time, since the specified start time has already passed, their participation starts at the same time they join the study. The participation continues until the specified end time. Therefore, for all participants who join the study before the start time, the participation duration will be identical, equal to the duration between the start and end times. For those who join the study after the start time, but before the end time, the participation duration will be shorter, depending on how long after the start time they joined. No participant can join the study after the specified end time. **Examples:** Assume the _Participation Start Time_ is set to Oct. 15th, 2020 00:00 and the _Participation End Time_ is set to Nov. 16th, 2020, 00:00. | Participant Join Date | Participation Start | Participation End | | --------------------- | ----------------------------- | ----------------------------- | | Sep. 5th, 2020 10:15 | Oct. 15th, 2020 00:00 | Nov. 16th, 2020, 00:00 | | Oct. 12th, 2020 19:15 | Oct. 15th, 2020 00:00 | Nov. 16th, 2020, 00:00 | | Oct. 25th, 2020 09:00 | Oct. 25th, 2020 09:00 | Nov. 16th, 2020, 00:00 | | Nov. 20th, 2020 11:45 | N/A (participant cannot join) | N/A (participant cannot join) | ### Setting Start and Duration, Marking End Checkbox In this case, if participants join before the specified start time, their participation does not start until the start time. If participants join after the start time, their participation starts at the same time they join the study. Either way, the participation will be finished after _Duration_ days (24 hours, not full calendar days), which is calculated based on the start time for each participant. In this scenario, most participants start and end their studies at the same time. However, if a participant joins a study late, they will still participate in the study for the same number of days, but they will finish their participation later. **Examples:** Assume the _Participation Start Time_ is set to Oct. 15th, 2020 00:00, and the _Participation Duration_ is set to 14 days. | Participant Join Date | Participation Start | Participation End | | --------------------- | --------------------- | --------------------- | | Sep. 5th, 2020 10:15 | Oct. 15th, 2020 00:00 | Oct. 29th, 2020 00:00 | | Oct. 12th, 2020 19:15 | Oct. 15th, 2020 00:00 | Oct. 29th, 2020 00:00 | | Oct. 25th, 2020 09:00 | Oct. 25th, 2020 09:00 | Nov. 8th, 2020, 09:00 | | Nov. 20th, 2020 11:45 | Nov. 20th, 2020 11:45 | Dec. 4th, 2020, 11:45 | ### Setting End and Duration, Marking Start Checkbox In this case, a participant starts as soon as they join the study. The participation continues for the number of days specified by the _Duration_ unless that falls after the specified end time. In this case, the participation will be cut off at the specified end time. No participant can join after the specified end time. **Examples:** Assume the _Participation End Time_ is set to Nov. 15th, 2020 00:00, and the _Participation Duration_ is set to 14 days. | Participant Join Date | Participation Start | Participation End | | --------------------- | ----------------------------- | ----------------------------- | | Sep. 5th, 2020 10:15 | Sep. 5th, 2020 10:15 | Sep. 19th, 2020 10:15 | | Oct. 12th, 2020 19:15 | Oct. 12th, 2020 19:15 | Oct. 26th, 2020 19:15 | | Nov. 5th, 2020 09:00 | Nov. 5th, 2020 09:00 | Nov. 15th, 2020 00:00 | | Nov. 20th, 2020 11:45 | N/A (participant cannot join) | N/A (participant cannot join) | ### Setting Start, End, and Duration In this case, if participants join before the specified start time, their participation does not start until the start time. If participants join after the participation start time, their participation starts at the same time they have joined the study. Participation ends at the earlier of the participation start time plus the duration, or the participation end time. No participant can join after the specified end time. **Examples:** Assume the _Participation Start Time_ is set to Oct. 15th, 2020 00:00, the _Participation End Time_ is set to Nov. 15th, 2020 00:00, and the _Participation Duration_ is set to 14 days. | Participant Join Date | Participation Start | Participation End | | --------------------- | ----------------------------- | ----------------------------- | | Sep. 5th, 2020 10:15 | Oct. 15th, 2020 00:00 | Oct. 29th, 2020 00:00 | | Oct. 16th, 2020 19:15 | Oct. 16th, 2020 19:15 | Oct. 30th, 2020 19:15 | | Nov. 5th, 2020 09:00 | Nov. 5th, 2020 09:00 | Nov. 15th, 2020 00:00 | | Nov. 20th, 2020 11:45 | N/A (participant cannot join) | N/A (participant cannot join) | ## Modifying Study Participation Period You can change the values for participation start time, end time, and duration, at any time, even while the study is in the field and enrollment is in progress. Any changes will be applied to future participants. Note that the changes do not apply to the participants currently enrolled in the study. That is because Avicenna has already calculated their individual participation period, and stored it for them. If you want to change the individual participation period for the currently enrolled participants, you need to [manually adjust](#modifying-participants-participation-period) them. ## Modifying Participants' Participation Period You can modify the participation start and end time for each participant individually or a group of participants and set them to any value necessary. Avicenna adjusts the participant's activities scheduling accordingly. You can read more about how these adjustments happen in the [Triggering Logics](../activities/triggering-logics.md) section. To change the start and/or end times of participants, follow the steps below. 1. Go to the Researcher Dashboard, and from the left panel, choose `Participation`. 2. In the `Participation` tab, find the ID of one or more intended participants, and select them by clicking on their checkbox. ![Modify participation period for individual participant](/assets/modify-participation-period-for-individual-participant.png) 3. From the menu at the top of the table, click the `Modify Participation Period`. 4. Set a new date for the start time and/or end time. You can also mark the end time as _Open_, just as explained earlier. 5. Press `Save` to apply the change. By pressing `Save`, Avicenna will save the new participation period for all of the selected participants, adjust their activities scheduling, and [reload](participation.md#reload-devices) the study settings on their mobile apps, if any. ## Time Zone When dealing with time, generally Avicenna takes the proper time zone into account. This prevents ambiguity when running studies across multiple time zones, or when the participants move across different time zones while they are part of a study. Internally, Avicenna stores almost all time values in UTC. This ensures consistency across calculations. Then, as a researcher or a participant uses Avicenna, those time values automatically convert to the user's local time zone. For example, if you are based in the Eastern time zone (-04:00 GMT), when you set the Participation Start Time to Oct. 15th, 2020 00:00, Avicenna saves this value as `2020-10-15 04:00:00-0000`. But when presenting this to you on your researcher dashboard, the value is converted to your local time zone (ET), and therefore, it's shown as Oct. 15th, 2020 00:00. Similarly, when a participant joins your study, Avicenna calculates their individual participation period in UTC, and then, displays this in their local time zone. In the above example, if a participant joins your study from your local time zone (Eastern Time), they will see their study starts on Oct. 15th, 2020 00:00. If they join from the Pacific time zone (PT), they will see their start time as of Oct. 14th, 2020 21:00 (as PT is 3 hours behind ET). ## My Progress Activating this feature allows participants to access the _My Progress_ page under the _Optional Activities_ section on their study homepage. When a participant taps on the _My Progress_ button, it presents a view of all the activity sessions of the participant followed by their [status](../activities/activity-sessions.md). This is useful especially if you want to compensate your participants for their participation or if you have a rewarding or gamification system integrated into your study. ![My Progress button on the participant's study home page.](/assets/4143-1-1.png) ![A history sample of activity sessions of a participant's dashboard.](/assets/4143-2.png) To enable this feature, go to the [Basics Page](../study-setup-and-deployment/create-a-new-study.md#basics-page) of your study and press the Edit button from the top panel. ![The Edit button on the Basics's page.](/assets/4143-3.png) Scroll down to the end of the page and enable the _Participants Progress Page_ to see its properties. ![The button of Participants Progress Page.](/assets/4143-4.png) ### Grouping This property lets you define how the content of the _My Progress_ page should be categorized. We provide three options here: _Monthly_, _Weekly_, and _Daily_. In the following picture, you can see three examples of setting this property to _Monthly_, _Weekly_, and _Daily_ from left to right respectively. ![Three sample results of setting Participants Progress Page to Monthly, Weekly, and Daily respectively from left to right.](/assets/4143-5.png) ### Months/Weeks/Days to be shown This option allows you to indicate how many months/weeks/days in the past and future will be presented. Note that not all the upcoming sessions you expect will have been created yet. Therefore, Avicenna will only show sessions that have been created and are within the specified range. See more information [here](../activities/triggering-logics.md#future-session-generation). ![The button of Months/Weeks/Days To Be Shown](/assets/4143-6.png) ### Sort By This option allows you to set the order by which the progress should be presented. #### _Ascending Order_ Shows the earlier activity sessions first. #### _Descending Order_ Shows the later activity sessions first. ### Page Title This is the title of the page that participants see when they open the _My Progress_ page. By default, the Page Title is _My Progress_. ### Page Description This option allows you to set a description for this page which will be shown to your participants when they open the _My Progress_ page. ![The buttons of Sort by, Page Title and Page Description.](/assets/4143-7.png) --- sidebar_position: 4 --- # Localization Inclusive research initially referred to studies that employed approaches designed to work with participants who have learning or intellectual disabilities. Scholars are increasingly expanding the scope of this definition to cover any research project that attempts to work with groups of people who are usually neglected in studies. These people could belong to minority nationalities, races, sexual orientations, or gender identities. They could come from lower economic classes and underrepresented age or language groups. One of the most common and effective methods applied by researchers to achieve such inclusivity is localization. Researchers can appeal to a more diverse language group, include a larger collection of participants, reach less biased conclusions, and increase the applicability of their research results. Localization in Avicenna can be divided into two general categories: localization of the participant app interface and localization of the study content (i.e., multilingual studies). Each of them is explained below. But first, let's see which languages are currently supported by Avicenna and how we can support a new language. ## Supported Languages Avicenna supports the following languages for both [the participant app interface](#app-interface-localization) and [study content](#study-content-localization): - Catalan - Chinese - Dutch - English - French - German - Italian - Persian (Farsi) - Portuguese - Slovenian - Spanish - Spanish Colombian - Urdu - Welsh - Zulu ### Supporting a New Language If you want to support a new language for your study, the general process is as follows: 1. Translate all the text content used in the participant app interface. This can be done by you (the researcher) or by us. 2. Update the participant apps to include the new language and the corresponding translations. 3. Adjust our researcher dashboard to show the new language and let you add the new language to your study. :::info This might incur additional costs. [Contact us for the details.](mailto:support@avicennaresearch.com) ::: ## App Interface Localization [The Avicenna participant app](enrollment.md#avicenna-participant-app) automatically sets its user interface language to match the system language by checking and updating it each time the app is opened. If Avicenna is not available in the system language, it switches to English by default. Participants can also choose the language by opening the Avicenna app, going to the `Settings → Languages`, and then selecting their desired language. This will override the language of their device, and instructs Avicenna to always appear in the language they chose, regardless of the language of their device: ![Participants can choose the language of the app interface and their studies through Settings.](/assets/study-setup-localization-app-languages.png) :::info If you are interested in helping us with translations in your local language, we would love to [hear from you](mailto:support@avicennaresearch.com). ::: ## Study Content Localization Avicenna supports creating studies where the content, for example, the consent materials, survey questions, or notifications, are translated and available in multiple languages. This way every participant interacts with the study using their app language, wherever applicable. ### Adding Localization By default, Avicenna assumes your study is only available in one language. We refer to this as the _Base Language_. It can be any language. For example, if your participants are predominantly familiar with Dutch, you can consider the _Base Language_ to be _Dutch_. Note that you do not have to set _Base Language_ to anything. _Base Language_ just refers to the language of the content you enter in your study when no language is chosen. Now, you may choose to have your study only in one language, for example, Dutch. In this case, all you need to do is enter all fields of study in Dutch. Hence, the participants will also see the study in Dutch. Note that Avicenna doesn't actually know which language you're using as the _Base Language_. If you choose to add other languages to your study, you can do that through the researcher dashboard by selecting your study and navigating to the `Basics` page. Towards the bottom of the page, you will find the `Localization` table. ![Localization table for a study including no languages by default](/assets/study-setup-localization-study-languages-empty-list.png) As you have not added any localization, you will notice that the table is empty. Click on `Add` to add a new language. ![Dialog to add a new language to the study](/assets/study-setup-localization-study-languages-add.png) For example, you may decide to add an English translation for your study as well, for those participants who cannot understand Dutch. In this case, you can add `English` to your study localization. As a result, your study will have two languages: the _Base Language_ which is Dutch, and English. If your study contains at least one localization, like the last example, the Researcher Dashboard will show a _Language Selector_ option next to all text, and in some cases image fields across the entire study, as shown below: ![Language selector on Edit Study Basics dialog](/assets/study-setup-localization-edit-study-basics-language-selector.png) Sometimes, you might find the _Language Selector_ at the top of a dialog, in a section next to the title, or in a tab (like the `Settings` tab of activity editors). In such cases, all available fields in that dialog, section, or the whole page (in the case of activity editors) are considered translatable. So, you can provide translations for all of them by simply changing the localization in that selector, as shown below: ![Language selector on Change Study Background dialog](/assets/study-setup-localization-edit-study-background-language-selector.png) In this case, when you are adding content to a given field, by default the _Language Selector_ (hence the content you want to modify) will be in the _Base language_. You can open the _Language Selector_ next to the field, choose one of the localizations, and then enter/select the translation of that content into the new language. :::info The _Base Language_ can be any language, not necessarily one of the languages listed here. Localization can also be done in any language of your choice. In theory, you can add the content of the _Base Language_ in a language like Dutch, and add the same Dutch translation as well. While this is possible, it does not make sense semantically and will have no impact on how Avicenna shows the localized content. ::: ### Displaying Localized Content If your study is available in multiple languages, Avicenna chooses the right language before showing any content, such as the app homepage, a survey, or a notification. The language is detected based on the following algorithm: 1. Avicenna checks whether the participant has chosen a language in the app's Settings. If yes, Avicenna uses it as the participant's preferred language. 2. If no, Avicenna checks whether the participant's device has been set to a specific language. If yes, Avicenna uses it as the participant's preferred language. 3. If no custom language is chosen from steps 1 and 2, Avicenna sets the participant's language to _Base_. 4. For showing every study content, Avicenna checks whether the content is provided by the researcher in the participant's preferred language. 5. If the content is available in the participant's preferred language, then Avicenna shows the content in that language. 6. If the content is not available in the participant's preferred language, the _Base_ version of the content is loaded and shown. Note that you should always provide the _Base_ version of each content. So Avicenna can always fall back to displaying the _Base_ content. ### Removing Localization To remove a given localization from your study, open the Researcher Dashboard, select your study, and navigate to the _Basics_ page. In the _Localization_ table, select the languages you want to remove, and press `Remove`. You'll be prompted with a confirmation dialog. If you confirm, the selected localizations and all translated content related to them will be removed. :::note This action cannot be undone. If you have entered a substantial amount of localized content, removing the localization will delete all of it. ::: --- sidebar_position: 5 --- # Eligibility Screening Avicenna allows screening potential participants in your study against certain inclusion or exclusion criteria and only allows those to join your study who meet the criteria. This is achievable by creating an [Eligibility Survey](../terminology.md#eligibility-survey) for your study, adding the necessary questions, and then setting a [criteria](../activities/criteria.md) based on these questions. In this section, we explain how this can be done in Avicenna Research. ## Eligibility Survey You can screen your participants for eligibility by creating an _Eligibility Survey_. Such a survey is asked of prospective participants just before joining your study. Based on their responses, a participant might be eligible to join or not. To add an _Eligibility Survey_ to your study, start by navigating to the _Researcher Dashboard_ and clicking on the **Activities** page on your Researcher Dashboard. On the _Activities_ page, click on the `Create New Activity` button. Then click on the **Eligibility Survey**. In the `Content` page of your new survey, add the questions you want to ask participants when they're trying to join your study. After adding the questions, go to the **Settings** tab on the right side. Considering the questions you have added, enter valid [Criteria](../activities/criteria.md). These criteria determine under what conditions a participant is considered eligible and allowed to proceed and respond to the study, and which responses can mark the participant as ineligible. Then, on the `Preview and Publish` page, [publish your survey](../surveys/README.md#publish-surveys). :::note There is no limitation on the number of times a prospective participant can respond to the eligibility survey. If they are marked as ineligible on their first try, they can try it again and respond to the eligibility survey for the second time. ::: You can [view responses](../surveys/view-responses.md) to your Eligibility survey by going to the **Activity Responses** page. --- sidebar_position: 6 --- # Enrollment Participants can join your study by installing the Avicenna app on their Android or iOS phone or tablet. Alternatively, they can use Avicenna for the web through their phones' or laptops' browsers. ## Avicenna Participant App Participants can use any of the following to sign up and join a study: - [Android app](https://play.google.com/store/apps/details?id=com.ethica.logger) - [iOS app](https://apps.apple.com/app/avicenna-research/id1137173052) - [Web-based interface](https://avicennaresearch.com/app/) Avicenna for iOS supports iOS version 13 and above, which is reported to cover [more than 99% of all iPhone devices](https://developer.apple.com/support/app-store/). Avicenna for Android supports Android version 4.2 and above (API version 17+) which [covers 99.2% of Android devices](https://developer.android.com/about/dashboards/index.html). These percentages ensure that almost all participants can join your study regardless of the type of phone they own. Therefore, you do not have to introduce selection bias during the enrollment based on the device type. Additionally, participants can access Avicenna through the web-based interface, and use that to join your study. Avicenna offers almost identical features across Android, iOS, and the Web, ensuring a comparable experience for participants regardless of the platform they use. However, certain platform-specific features, such as sensor-based data collection or in-app notifications, may vary. The availability of each feature is explained in the respective documentation. Unless stated otherwise, you can assume all features described throughout the documentation are available on Android, iOS, and the Web. Participants can use multiple devices throughout their participation. For example, they can start by using their Android phone and occasionally log in to their account on their personal computer. Then, partly through the study, they can switch to an iPhone device. As long as they use the same account, Avicenna ensures their data is in sync across all of their devices. Furthermore, Avicenna keeps track of the data uploaded from each device. You can use the [Participation page](participation.md) to check different devices a given participant has used, and the data uploaded from each device. ## Sign up Process If participants install the Avicenna app on their phones and sign up for a new account, a `Participant` account is created for them by default. When signing up on the web, participants need to explicitly choose that they are a participant, as shown in the image below: ![Participants must choose their account type while signing up on the web](/assets/enrollment-sign-up-web-participant-vs-researcher-selection.png) During the sign-up process, participants are asked to enter their email address and choose a password. These credentials allow participants to access their account and their data from any other devices, such as another smartphone (e.g., when switching phones) or via a web browser. In this case, all their data will start to synchronize with the new device immediately. For example, if a participant is expected to receive a _Survey_, they will receive it on their new device, as well as any other device they are logged into. This allows participants to continue with the study seamlessly after switching from their phone to their personal computer or if they have to switch phones. If using email addresses causes privacy concerns in your study, you can instruct participants to use a variation of a [catch-all email address](https://gmail.googleblog.com/2008/03/2-hidden-ways-to-get-more-from-your.html). After participants sign up or log in, they will remain logged in until they sign out. Avicenna also offers a password recovery option. If a participant forgets their password, they can request a password reset link via email. ## Study Enrollment There are 3 ways for a participant to enroll in your study: ### Using Registration URL The easiest way for participants to join your study is by using the `Registration URL`. Each study in Avicenna has a unique URL, for example: - [https://www.avicennaresearch.com/study/805](https://www.avicennaresearch.com/study/805) This URL which is based on the Study ID points to your study's homepage in Avicenna. You can think of this page as the study's _landing page_. If a participant has already installed the Avicenna app on their phone, clicking on a Registration URL will take them directly to the study's registration page inside the Avicenna app. Otherwise, if they still don't have it on their smartphones, the link will open on their phone's browser; so, they will see the following dialog asking them if they want to enroll in the study: ![Avicenna web app study home page enrollment dialog in Android](/assets/enrollment-study-url.png) Here, participants can see the name and description of your study to check whether they're on the correct page. :::info If your study already has a dedicated web page, you can modify it to behave just like the web page shown above. This way, you can use your own web page's URL as the study's enrollment URL, and participants can register for your study by visiting your web page. Please contact [Avicenna Support](mailto:support@avicennaresearch.com) for the required modification details. ::: If the participant is visiting this page on a smartphone, clicking on the `Participate` button will check whether the individual has the Avicenna app installed. If yes, the Avicenna app will be opened, and after the person logs in they will be presented with your study's consent materials. If not, the person will be taken to the Google Play Store or Apple App Store to install the Avicenna app. After installing and opening the app, Avicenna will automatically detect the study which the user wants to join and show a custom welcome screen based on the study: ![Using study background for app branding in Android](/assets/enrollment-study-url-study-background-app-branding.png) This allows you to brand the Avicenna app for your study from the very first step. Additionally, there is no need for the user to enter any `Study Registration Code` to join your study. As soon as the user logs in or signs up with the Avicenna app, they will see your study's consent materials and can continue with the registration. If the participant is not using a smartphone, but using a computer web browser instead, and they are already logged into Avicenna as a participant, clicking on the `Participate` button will take them to the study registration web page. In case they're not already logged in to Avicenna Research, they'd be redirected to your study's `Welcome` page. So, they can sign up or log in and proceed with the registration process. ![Custom sign-up and login page in Avicenna web-based app](/assets/enrollment-study-url-custom-signup-page-web.png) :::info If the study has an [Eligibility Survey](eligibility-screening.md), the participant app will prompt that first and if the participant is eligible then the consent materials will be shown. ::: ### Using Registration QR Code Each study has a unique `QR Code` that directs to its `Registration URL`. Scanning the QR Code with a phone or tablet's camera eliminates the need to manually enter the URL. For more details on enrollment using the Registration URL, please refer to the above [section](#using-registration-url). ### Using Study Registration Code Each study has a unique `Registration Code`, which is the same as the [Study ID](../terminology.md#study-id). Participants can enter this code inside the Avicenna app to join your study. You can find the study's Registration Code on the `Basics` page located on the Researcher Dashboard. ## Enrollment Types You can use the `Enrollment Type` on the `Basics` page to specify who is allowed to join your study. The `Enrollment Type` can be set to one of three options, as explained below. ### Public This option makes the study accessible to the public. Anyone can join the study provided they have the study's [Registration Code](#using-study-registration-code) or [URL](#using-registration-url). You can take advantage of this feature by posting the study’s Registration URL, Registration Code, or Registration QR Code on your social media pages or various group chats, or putting them on a poster, etc. Additionally, you can still invite specific participants to join your study through the [Invitation-based](#invitation-based) enrollment type. However, having an invitation is not a requirement for joining. ### Invitation-based In contrast to [Public](#public) studies, where anyone can join, `Invitation-based` studies require that individuals be specifically invited before they can participate. To invite individuals to the study, you must have their email addresses. It's important to note that invited individuals are not required to have an Avicenna account at the time of invitation. However, they must create an account using the email address to which the invitation was sent to join the study. For details on how to invite participants to your study, please refer to the [Invite Participants](#invite-participants) section. ### Closed If you do not wish to enroll any new participants in your study, either temporarily or permanently, you can set the study status to `Closed`. This will prevent any individuals, whether they have been invited or not, from joining your study. You can change the status of your study to Closed, or from Closed to other statuses, at any time. ## Participant Type Avicenna offers two types of participants: `Test` and `Main`. Test participants are used for testing purposes (e.g., testing the study protocol). All the functionality of the participant apps is available to test participants so you can do your tests thoroughly. On the other hand, the main participants are the actual participants of the study. By default, all participants who join your study with a trial license are considered test participants. In contrast, participants who join your licensed study are considered main participants unless they are invited as test participants in the first place. You can later [change the main participants to test participants](participation.md#set-as-test-participant). By utilizing this distinction, you can then filter out test participants' data on all data pages within your researcher dashboard, enabling a more accurate analysis. ## Invite Participants When the [enrollment type](#enrollment-types) of your study is not set as Closed (i.e. it's either Public or Invitation-based), you can invite new participants to join your study. The Participation page offers you four options to invite new participants. You can invite participants by: - Sending them an invitation email - Sending them the [Registration URL](../study-setup-and-deployment/enrollment.md#using-registration-url) - Sending them the [Registration QR Code](../study-setup-and-deployment/enrollment.md#using-registration-qr-code) - Sending them the [Study Registration Code](../study-setup-and-deployment/enrollment.md#using-study-registration-code) ![Invite participants options on the Participation page](/assets/participation-invite-participants.png) :::info In the screenshot above, our study has more than one site. That's why you can see the `Invite via Email Address` button has grayed out until a site is chosen from the site selector at the top of the page. In a multi-site study, if you are inviting participants to a certain site, when they join the study, they will automatically be assigned to that site. ::: Clicking on the `Invite via Email Address` will open the _Invite Participant_ dialog. ![Avicenna study participant invitation dialog](/assets/participation-invite-participants-dailog.png) Here you can enter the list of participants you want to invite and choose to whether they should be considered as test participants. You can enter up to 100 names at once, each in a separate line. A given invitation must start with the email address of the invited participant. It can also include the first and last names of the individual, though it's not mandatory. The following lines each represent a valid invitation entry: ```text bob.smith@example.com,Bob,Smith alice.smith@example.com ``` After you enter all the invitations, you can press Invite to create the invitations. Shortly after pressing Invite, Avicenna will show another dialog with the result of the invitations. ![Avicenna study participant invitation result](/assets/participation-invitation-result.png) As you can see in the image above, invitations are either created successfully or have failed due to one of the following reasons: - The individual you have invited is already registered with Avicenna as a researcher. Avicenna does not allow researchers to participate in a study ([learn more about this](../terminology.md#researcher)). - The individual you have invited is already part of this study. Therefore, you cannot invite them to join the study again. If, while creating the invitations, you chose to send an email to participants about their invitation, Avicenna sends them an email with the URL to join the study. By default, the content of the email will be the following: **Email Subject:** ```text Study invitation: {{Your study name goes here}} ``` **Email Body:** ```text Hi {{Individual's first name, if available}}, {{Your name goes here}} from {{Your organization name goes here}} has invited you to join "{{Your study name goes here}}" research study. Please click on the link below to download the Avicenna app and join the study: {{Registration URL will be placed here}} If you don't have the Avicenna app installed, the above link will ask you to download it first. If you have any problem with the link, you can just directly download the Avicenna app from Google Play or App Store, and after you register, join the study using registration code {{Your study registration code goes here}}. Also, please make sure you use {{Participant's email address which is invited to the study goes here}} as your email address while registering. Thanks for helping advance the science, The Avicenna Research team ``` See [Notification Templates](notifications.md#notification-templates) for more details on how to customize the content of the invitation email. :::info Before inviting participants, you need to have the email address of the individuals you want to invite to the study. While invitees don't need an Avicenna account at the time of invitation, they must create one using the invited email address to join the study. ::: ## Pending Invitations Tab The `Pending Invitations` tab on the [Participation](participation.md) page will be visible when there is at least one invitation pending. Any sent invitation will be added to the invitation table first. Once a participant joins the study, their invitation entry will be removed from that table, and you can find them in the `Participation` tab. ![Pending Invitations tab of the Participation page](/assets/participation-pending-invitations.png) In the image above, you can see three main details: the `Participant ID`, the date and time they were invited, labeled as `Invited On`, and the `Participant Type`. If you want to know which site each participant is invited to, simply select the `All Sites` option from the site selector. This will add an extra column called `Site` to the table. But, if you pick a specific site from the dropdown, the Site column will disappear because it's only showing invitations for that one site. Also, if showing personally identifiable information is enabled for your study, you will be able to see the email address, and first and last names for each invitation. :::info On any other page of your Researcher Dashboard, and in any other part of the system, you will not see the email addresses or the names of the participants. Instead, you will see their labels or IDs. ::: To delete or resend invitations, click either on the _checkboxes_ beside the Participant IDs you want to take action on or on the ellipsis menu at the end of each row. Then, select the action that you want to perform, either `Delete` or `Resend Invitation`. ## Troubleshooting ### Invitation is pending but the participant already joined the study If a participant appears on the `Pending Invitations` tab but says they joined the study and are participating already: 1. Verify they joined the correct study by confirming the study ID/title they see matches your study. 2. Ask the participant to check their email address under the `Settings → Notifications` page and whether it matches the one you used for the invitation. Do the same for the participant ID. They can find that at the bottom of the `Settings` page (as `User ID`). --- sidebar_position: 7 --- # Participation The Participation page on the Researcher Dashboard shows you an overview of all the participants in your study, including the ones who are participating and those who have been invited. On this page, we will walk you through the Participation and Pending Invitations tabs as well as explain the actions that you can perform. ## Participation Tab The Participation tab provides you with a table where you can see a list of all the participants of your study, whether enrolled or dropped out. This table displays additional information related to your participants which will be explained below. ![The participant information on the Participation page](/assets/participation-participant-information.png) Each row of the table contains the following Columns: - **Avicenna ID**: This is the participant's [ID](../terminology.md#user-id) in Avicenna. - **Start Time**: This shows the calculated [Participation Start Time](participation-period.md) for your participants. - **End Time:** This shows the calculated Participation End Time for your participant. - **Label**: This shows the label you have assigned to a particular participant. Labels help you better identify participants within the study. - **Status:** This shows you whether the participant is active or dropped out of the study. - **Last Recorded Data Time**: This shows the last time when Avicenna received sensor data from a participant, or when an activity session for the participant was completed, canceled, expired, or blocked. - **In Operation**: If your study includes sensors, this column displays the percentage of the time that the app was running and collecting sensor data from a given participant. For example, in the image above, the participant with _ID 59982_ has collected sensor data 26% of the time using their app(s). - **Session Stats**: This shows statistics on the status of the sessions (with a past scheduled time) related to a given participant, which can be seen as a summary of their adherence to the Activity requirements. In the image above, you can see that the participant with the _ID 58830_ has completed 7, canceled 1, and not answered 3 sessions. The remaining 6 sessions of this participant have a Blocked status. Please refer to [Activity Sessions](../activities/activity-sessions.md) for more details on sessions and what statuses they can hold. - **Devices**: This column gives you the number of devices that are used by the participant. By clicking on the eye-shaped button, you can see the list of devices. For each device, the list shows a unique identifier. Each data record received from a given participant is tagged with the relevant device ID. So when analyzing the data, you can see which device was used to upload which data. Furthermore, for each device, you can see the model and manufacturer as seen in the image below. ![Participants’ device information](/assets/participation-device-information.png) ### In Operation Event Plots If your study records sensor data, when a participant joins your study, the Avicenna mobile app will continuously run on their phone behind the scenes and collect the requested data. The app also sends a report to the Avicenna server on how often it was running and collecting data, and how often it was terminated, for example by the participant or due to the phone being turned off. The `In Operation` shown for each device can give you a good estimate of when the app was running on the participant's phone, and when it was not. For example, in the image above, you can see that the app was running for a short time on the Xiaomi device. ### Sensor Event Plots The sensor event plots show when sensor data exists from a certain device (colored region), and when it does not (gray region). As you hover the mouse over the plot, a tooltip appears to show the time which that part of the plot presents. If the area under the mouse is colored, it means that the participant has uploaded the relevant sensor data during this time window from the specified device. If there is no sensor data collected and received from a specific device, instead of a plot you'll see "No Data". ![Sensor Data bar](/assets/participation-sensor-event-plot.png) ### Data Filtering You can use the **Filter** button to set conditions, sort, and specify which columns you want to see for each participant. Finally, you can export and download the list of participants based on what you see in a CSV file format. On the Participation page, you can filter the data based on many different fields in different categories including _Participant_, _Devices_, _Sessions_, _Survey Responses_, and _Notifications_. See [the Data Filtering](data-filtering.md) for how to use this feature. ![Data Filtering on the Participation page](/assets/participation-data-filtering-example-1.png) ## Participant-related Actions In the Participation tab, it is possible to perform several actions, including `Edit Label`, `Modifying Participation Period`, `Reload Devices`, `Set as Test Participant`, `Change Site`, `Drop from Study`, and `Delete`. You can perform some of these actions on multiple participants by selecting them first and then clicking the desired action on the table header. ### Modify Participation Period When a given participant joins your study, the Avicenna app calculates their individual [Participation Period](participation-period.md). You can see the Participation Period for a given participant in the table labeled as `Start Time` and `End Time`. For example, in the image below, Participant _ID 58830_ joined the study on Feb. 25, 2023, and will be part of the study until Mar. 11, 2023. ![Modifying the Participation Period](/assets/participation-modifying-participation-period.png) You can modify this period for one or more participants by selecting the intended participants and clicking on the `Modify Participation Period` button. Alternatively, for each participant, you can click the ellipsis menu to the right of the table to access the actions available. Note that this solution can only be applied to one participant at a time. After selecting the participants, set a new start and end date from the dialog, and then click on Save. :::info When you modify the Participation Period for a given participant, Avicenna automatically adjusts their Activity sessions based on the new period. For example, if you set their Start Time to a later time, the responses provided prior to this time will not be accessible anymore. Or if you reduce the End Time, the sessions scheduled after the new End Time will be removed. You must be cautious about how you are modifying this period. On the other hand, when the Participation Period is modified, Avicenna won't delete collected sensor data for the participant, no matter what the new Start Time and End Time are. ::: ### Reload Devices Avicenna apps for Android and iPhone are capable of working offline. To do so, occasionally the app connects to the server, downloads all study settings, and uses those settings as the basis for its operation. If you modify the study settings while participants are already enrolled in the study, you might make those settings invalid and out of date. You can wait for each participant's app to sync itself with the latest changes, but this periodic reload can take about 30 days [if nothing else causes a reload](./audit-trail.md#24-study-update-started). Alternatively, you can initiate this sync yourself. To reload the participants' devices, go to the Participation page on the Researcher Dashboard, select the participants, and click on `Reload Devices`. ![Reload Devices as a Researcher](/assets/participation-reload-device-researcher.png) Doing this will instruct Avicenna to send a message to the participants' devices and perform the reload. The message is often received by the app right away, or in case they are offline, as soon as they become online again. An alternative solution is to ask participants to reload studies from their Avicenna app. To do so, they should open the Avicenna app and click on `Settings`. Then, they need to tap the `My Studies`. Finally, they need to press the `RELOAD STUDIES FROM SERVER` button to reload the latest study details from the server. ![Reloading studies from the server](/assets/participation-settings-mobile-app-reload-studies-from-server.png) ### Change Site For multi-site studies, researchers can change the site associated with one or more participants. This might be needed if a participant moves to a different location or there was an error during their initial enrollment. To change the site for the participants: - Select the intended participants. - Click on the `Change Site` button. - From the dialog that appears, choose the new site for the participants. - Click on `Change`. :::note Changing a participant's site will associate all their collected or future data with the newly assigned site. ::: ### Set as Test Participant > This feature is only available for licensed studies. You can change the type of a participant from `Main` to `Test`. This is useful when you want to test a licensed study with a test participant account but you joined the study as a main participant. See the [Participant Type](enrollment.md#participant-type) section for more details on these two types of participants. ![Set as Test Participant](/assets/participation-set-as-test-participant.png) :::note You can only change the participant type within the first three days after the participant's [Join Time](../terminology.md#join-time), and you cannot change this for anonymous, dropped, or dropped-out participants. ::: :::note The action is irreversible and you cannot change a test participant back to a main participant. If you want to change a test participant to a main participant, you need to delete the test participant. In this case, the participant will lose all their data and will have to join and start from scratch as a main participant. ::: ### Drop from Study You can choose to exclude one or more participants from the study. This will stop all data collection immediately and remove the study from their app (you may need to reload participants' devices). To drop a participant from the study, you just need to select the participant, click on the `Drop from Study` button, and confirm. For more details on dropping out of a study, you can refer to the [Study Dropout](study-dropout.md) section. ![Deleting and Dropping actions](/assets/participation-drop-delete.png) ### Delete from Study This option allows you to remove a given participant from the study, and delete all their associated data as well. In this case, Avicenna will delete the participation record for this participant, any collected sensor data, and any collected Activity data as well. To delete participants from your study, you need to select one or more participants and then click on the `Delete` button. The participant may join the study again. If the study is [invitation-based](enrollment.md#enrollment-types), they will need a new invitation to join the study. Also, if they join the study again, Avicenna will consider them as a new participant and recalculate their Participation Period. ## Capture Reason for Changes in Participants' Data Researchers can enable a feature that will force them to provide reasons for any changes that affect participants' data, including modifying the participation period, changing labels or sites, dropping them from the study, editing survey responses, etc. This provides transparency and accountability, empowering researchers to validate the integrity of any modifications. To enable this feature for your study, navigate to the `Basics` page of the researcher dashboard. On that page, click on `Edit`, and then on the `Edit Study` dialog, enable `Capture Reason for Changes`. By default, the feature is disabled. ![Enabling Capture Reason for Changes](/assets/study-settings-capture-reason-for-changes-in-participants-data.png) Once enabled, researchers must provide reasons for changes made to participants' data. For example, the following image shows that editing a participant's label requires a Reason now: ![Edit participant's label with a reason](/assets/participation-edit-label-with-reason.png) Reasons are recorded as part of the audit logs along with the changes made to the participants' data. See the following image for the recorded Reason we wrote when changing the participant's label: ![The audit log with the reason](/assets/audit-trail-log-with-reason.jpg) ## Show Participants' Personally Identifiable Information (PII) By default, Avicenna does not show participants' PII to researchers. Avicenna allocates a unique ID to each new participant and uses this identifier to store their data in the database. This ID is used throughout the platform to reference participant data, ensuring personal details like names and email addresses are stored separately from study-related data and remain inaccessible. However, **study owners** can choose to display participants' personal information for all researchers of the study. To enable PII visibility, navigate to the `Basics` page of the researcher dashboard. Click on `Edit`, and then on the `Edit Study` dialog, enable `PII Visibility`. ![Change PII Visibility](/assets/study-settings-pii-visibility.png) Once enabled, you can see some of the participants' PII on the `Participation` page or the corresponding exports. This includes the participant's first name, last name, and email address. ## Troubleshooting ### General steps to diagnose participation issues 1. Ensure that the participant is really part of your study. You might want to temporarily [enable PII visibility](#show-participants-personally-identifiable-information-pii) and look for them by their email address or name. 2. If the participant is using the Avicenna mobile app, make sure the app is the latest version. Simply check the App Store or Google Play and update the app if a new version is available. 3. Make sure that your participant's device date/time and their timezone is set correctly. 4. If you don't see the expected data on the researcher dashboard or the exported/downloaded file, double-check [the selected site (if your study is multi-site)](multi-site-studies.md#switching-between-sites) and the applied filter, if any. Note that some filters can be more complex and [exclude some columns/metadata](data-filtering.md#columns). 5. In case you modified the study or anything related to the participant (e.g., their participation period), check if the participant actually got the new changes since then. You can do this by finding [the "Registration Read" audit logs](../study-setup-and-deployment/audit-trail.md#70-registration-read) for the corresponding participant. If the participant is using the mobile app, you can [send a request to reload the study on the participant's app](#reload-devices). But if the participant is using the web app, they can simply refresh the page. 6. If you expected some responses or sensor data from the participant, make sure they successfully uploaded them. You can do this by finding [the "Data Sync Ended"](../study-setup-and-deployment/audit-trail.md#28-data-sync-ended), ["Automatic Data Upload Finished"](../study-setup-and-deployment/audit-trail.md#29-automatic-data-upload-finished), and ["Automatic Activity Response Upload Finished"](../study-setup-and-deployment/audit-trail.md#35-automatic-activity-response-upload-finished) logs. If your participant is using our mobile apps, you can ask them to try syncing the data manually (again) by going to the `Settings` page and tapping the `Sync Data` option. 7. Related to the previous item, if the participant was using the mobile app, check if they might have logged out of the app, cleared the app cache, or simply uninstalled the app, while they were offline. We won't be able to detect and log these cases. ### Study is finished but I still receive responses/data/logs from the participant 1. Check if [the participation period for that specific participant](#participation-tab) hasn't finished yet. You might have adjusted [the study's participation period or duration](./participation-period.md) after the participant joined the study. We don't adjust the participation periods for already-enrolled participants in such cases. You might want to [adjust the end time for that participant](#modify-participation-period). 2. The same is true if you simply change [the Enrollment Type](./enrollment.md#enrollment-types) to `Closed`. That will only prevent new participants from joining your study; it won't affect already-enrolled participants. 3. Check [the general steps to diagnose participation issues](../study-setup-and-deployment/participation.md#general-steps-to-diagnose-participation-issues). ### I can't find the participant, but I receive extra data (e.g., responses) from another participant This might indicate that two participants (probably partners) are using the same account for whatever reason. Note that [each participant in Avicenna has a unique Avicenna ID](../terminology.md#user-id); two participants can't have the same ID. Also, you might want to check [the general steps to diagnose participation issues](../study-setup-and-deployment/participation.md#general-steps-to-diagnose-participation-issues). --- sidebar_position: 8 --- # Notifications Avicenna’s Notifications functionality allows you to create and send customized notifications, whether automated or manually, to the researchers in your team or the participants. Before sending a notification, you need to specify the recipients, set the notification trigger, define when the notification should be sent, and a few other settings. All of these are combined into a notification template, which Avicenna uses to send one or more notifications. In this article, we will explore this functionality in depth. Currently, Avicenna supports two types of notifications: 1. **Participation Notifications:** These notifications are related to the study's participation events. At the moment, they can be configured to be sent when a participant is **invited** to the study, or when they **join** the study. 2. **Activity Notifications:** These notifications are related to the activities of your study. They are triggered when an activity session is released, [completed](../terminology.md#completed-session), [canceled](../terminology.md#canceled-session), or [expired](../terminology.md#canceled-session). ## Notification Templates A notification template, as the name suggests, outlines when to send notifications, their content, recipients, and other configurations. In most scenarios, you'll need a notification template to send any notification. The only exception is sending [one-off notifications](#one-off-notifications). ### Creating Notification Templates There are two ways to create a notification template. First, you can go to the Notifications page on your researcher dashboard and click on the Notification Templates tab. There, you can create, edit, and delete the notification templates in your study. Alternatively, you can go to the Activities page, choose an activity, and then click on the Notification Templates tab. There, you can create, edit, link, and unlink only the notification templates related to the current activity. This makes it **simpler** for you to configure notifications when you are creating your activity. :::note Notification templates created on the Activity Editor can be used for activity-related events only. This means that you cannot use them for participation-related events. This may limit your options when choosing what should trigger the notification. On the other hand, you can use Notifications page to create a notification template for both types of events. ::: #### Using the Notifications Page Navigate to the Notifications page on your dashboard and select the Notification Templates tab. Here you can create and manage all the notification templates of your study: ![Notification Template preview](/assets/notifications-templates-in-notifications-page.png) Clicking on the **Create Template** button shows you a dialog similar to the following. This dialog contains the parameters needed to create a notification template: ![Creating Notification Template](/assets/notifications-templates-create-dialog.png) We explain each parameter in depth below. **Label:** You can assign a label to each template. The labels are only used to better identify the templates on the list. **Recipients:** You can specify who will receive the notifications. The recipients can be either Participant or Researchers. If you choose the Participant, the notification will be sent to the relevant participant. If you choose the Researchers, you will need to specify the researchers. **Notify On:** Here you need to set what will trigger the notification. The available options include: - _**Study Invitation:**_ This template will be used when you invite a new participant to the study. If you have not defined a Study Invitation notification template for your study when inviting participants, Avicenna creates one by default. Note that this notification can be only sent via email. That’s because, at the time of inviting a participant to your study, the email address is the only information Avicenna has from the invited participants. :::info While all email notifications require participants to verify their email addresses first, Study Invitation templates are an exception. Here we assume the participant's email address entered by the researcher is a valid address. ::: - _**Participant Joined:**_ The template is used when a new participant enrolls in the study. This can be used to either send a welcome email to the participants, or to send a notification to the research staff and let them know that a new participant joined the study. Similar to Study Invitation, Participant Joined notifications can only be sent through email. - _**Session Released:**_ The template is used when a new activity session is prompted to a participant. - _**Session Completed:**_ The template is used when the prompted session is completed. For example, in case of survey activities, a survey session is completed when the participant responds to all of the questions and submits the answers. - _**Session Expired:**_ The template is used when the prompted session expires. If a participant does not complete the session within the allowed time window, the session will be considered an Expired Session. - _**Session Canceled:**_ The template is used when the prompted session is canceled. A session is marked as canceled when a participant explicitly indicates that they do not want to continue responding to a given session from a given activity. **Offset:** Offset allows you to set how long before or after the event the notification must be sent. :::note Only `Session Released` and `Session Expired` events can have negative offset values. This is because Avicenna can send notifications before an event only if it knows when the event will happen beforehand. ::: **Criteria:** You can define criteria that, when met, will trigger the notification. Consider a mental health study where participants are required to fill out daily mood logs through the Avicenna application. You want to ensure that the participants are not experiencing severe emotional distress, and if they are, you want to provide additional resources or support promptly. In this scenario, you can use criteria to monitor participants' responses and send notifications based on their input. This way you can customize your notifications and increase the compliance among your participants. For more information on how to use criteria in Avicenna, check [here.](../activities/criteria.md) **Language:** This field is only available if you have more than one language added to your study in the Basics page. You can specify the language of the notification. This is useful when you want to send notifications in different languages. For example, you can send the notification in English to those participants who chose English as their main language, and send the same notification in French to French-speaking participants. **Medium Contents:** In this field, you can specify the mediums through which Avicenna should send the notifications. We currently support three mediums: - _**Email:**_ Recipients, whether participants or researchers, need to verify their email address before they can receive email notifications. - _**SMS:**_ Recipients need to verify their phone numbers to receive SMS notifications. Also, this will incur additional cost on your study, and may incur additional charges on the recipient as well. To enable this medium for your notifications, please contact [Avicenna Support](mailto:support@avicennaresearch.com). - _**In-App:**_ Recipients should have the Avicenna app installed on their phone to get the In-App notifications. As the Avicenna app is only designed for participants, this notification medium is used for the study participants and cannot be used for the research staff. For each of the selected mediums, you also need to write the content of the notification. For email, this will be a subject and a body of the mail. For in-app, this will be a title and a description. For SMS, this will be the content of the message. In case you want to inform the recipients about the ID and the name of the study or the activity they are participating in, you can use placeholders by clicking on the `Add Placeholder` drop-down menu on the top right of your text editor. For example, if you want to add the name of the study to the email body or description of your in-app notification, you can click on `Add Placeholder` and choose `Study Name`. This will add the placeholder to the body field. When the notification is sent, the placeholder will be replaced with the actual name of the study. ![Adding placeholder to content of your notification template](/assets/notification-template-adding-placeholder.png) :::info **Notify On** options have different placeholders. For example, the Session URL and its placeholder are available for `Session Released`, but it will not work for `Participant Joined`. The reason is there is no session URL for a participant that has just joined and using it here is meaningless. In this case, you will see an error message that this placeholder is not supported. | ![Error message for not supported placeholders](/assets/notification-template-not-supported-placeholders.png) | | :-----------------------------------------------------------------------------------------------------------: | | Error message for not supported placeholders | ::: To make it easier, Avicenna will provide you with pre-created placeholders for the body or description of your notification according to what you choose for **Notify On** field. You can see how the placeholders may differ in the images below: | ![Placeholders for notify on participant joined](/assets/notification-templates-placeholders-for-participant-joined.png) | ![Placeholders for notify on session released](/assets/notification-templates-placeholders-for-session-released.png) | | :----------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------: | | Placeholders for notify on participant joined | Placeholders for notify on session released | After taking care of the fields above, press Create and your Notification Template will be created and immediately becomes active. #### Using the Activity Editor In the Activity Editor, you can create notification templates that belong to activity-related events (Session Released, Session Completed, Session Expired, and Session Canceled). To do this, after navigating to the Activity Editor, on the Notification Template page, click on the Create Template button at the top-right corner to create a new notification template. The process of creating a notification template here is similar to the one we already explained for the [Notifications page](#creating-notification-templates). You should keep in mind that creating a template in the Activity Editor will immediately link it to the current activity. This will be explained in more detail in the next section. | ![Creating Notification Template in the Activity Editor](/assets/notifications-templates-create-in-activity-editor.png) | | :---------------------------------------------------------------------------------------------------------------------: | | Creating Notification Template in the Activity Editor | ### Linking and Unlinking Templates to Activities By default, activities in Avicenna have no notifications linked to them. So the participants do not know whether they have a new activity unless they happen to open the Avicenna app at the right time. This is of course not ideal, and in almost all cases, you want to notify your participants to complete the activity. To do so, you must [create a notification template](#creating-notification-templates) and then link that to your activity in your study. This can help you manage your notifications among different activities and avoid having identical notification templates. To give you an example, let's say that you have four surveys in your study. You want your participants to be notified whenever a new survey is released. In such a case, instead of making a Session Released notification template for each one of the surveys, you can simply create one notification template and link it to all the surveys in your study. There are two ways to link a notification template to a given activity. First, if you [create your notification template using the Activity Editor](#using-the-activity-editor), the template will be linked to that activity by default. | ![Linking and unlinking a notification template](/assets/notifications-templates-linking-unlinking.png) | | :-----------------------------------------------------------------------------------------------------: | | Linking and unlinking a notification template | Alternatively, you can manually link an already-created notification template to an activity. In the Notification Templates page of the Activity Editor, you will see two tables: one for the templates already linked to the current activity, and another one for potential templates that can be linked. By clicking the link button on each row of the second table, as shown in the above image, that particular notification template gets linked to your activity. Doing so will move the template to the first table. Similarly, you can unlink a notification template from your activity by clicking on the unlink icon. ### Editing and Deleting Notification Templates You can edit or delete the notification templates in your study as needed. While editing a notification template can be done on both the Notifications page and the Activity Editor, you can only delete notification templates on the Notifications page. This is because each notification template may be linked to multiple activities, and deleting it from the Activity Editor for one activity can accidentally modify other activities in your study. The following table can further clarify what operations are accessible at what part of the researcher dashboard: | | **Notifications page** | **Activity Editor** | | ---------------------------- | ---------------------- | ------------------- | | **Create a NT\*** | Possible | Possible | | **Edit a NT** | Possible | Possible | | **Delete a NT** | Possible | Not Possible | | **Link a NT** | Not Possible | Possible | \* NT stands for Notification Templates. To delete or edit a notification template on the Notifications page: - Go to the Notifications page and choose the Notification Templates tab. - Click on the 3-dot button that you see on the right side of the table. - Choose the **Edit** or **Delete** options to initiate the related operation. | ![Editing and deleting a notification template in the Notifications page](/assets/notifications-templates-modify-in-notifications-page.png) | | :-----------------------------------------------------------------------------------------------------------------------------------------: | | Editing and deleting a notification template in the Notifications page | To edit a notification template in the Activity Editor: - Go to the Activities page, choose an activity, open the Activity Editor, and then go to the Notification Templates page. - Click on the Edit button from the Actions column. ![Editing a Notification Template in the Activity Editor](/assets/notifications-templates-modify-in-activity-editor.png) :::caution Keep in mind that you need to be careful when making changes to a notification template via the Activity Editor. Since a notification template might be linked to several activities within the same study, the modifications that you make to a linked template will affect the other activities as well. When you make changes to a linked template, the changes will be applied to all activities immediately. ::: ## Notifications Log If you open the Notifications page on your researcher dashboard, and click on the Notifications tab, you can see the list of all notifications Avicenna has sent to your study participant, and the list of notifications that are scheduled to be sent in the future, based on your notification template configurations. As you can see in the image below, for each notification, you can see: | ![Notifications Log](/assets/notifications-log.png) | | :-------------------------------------------------: | | Notifications Log | - The notification **ID** - The intended **recipient** - The notification **sender** (this will be Avicenna System in almost all cases) - The unique identifier of the related activity session (**session UUID**) - The **scheduled time** of the notification which tells you when the notification was sent or will be sent - The **activity name** that the notification belongs to - The notification **mediums** that tells you through which medium a given notification is sent - The **notification status**, which can be one of the following: - `Pending`: The notification is scheduled to be sent in the future. - `Partially Failed:` The notification was sent through some mediums, but it failed to be sent through one or more mediums. For example, the in-app medium was sent, but the email failed due to the participant’s email address not being verified. - `Failed:` This happens when a notification cannot be sent through any of the mediums. Also, if Avicenna fails to process a notification and send it due to technical reasons, the notification will be marked as Failed. - `Success:` The notification was sent successfully through all the mediums. - `Stale:` This means Avicenna could not send the notification on time due to technical reasons, and decided to skip it. :::info It's worth noting that when a session is blocked, expired, canceled, or completed, the associated upcoming Session Release notifications will be automatically deleted and will not be displayed. For further information on the session's status, please refer to the [Triggering Logics](../activities/triggering-logics.md). As an example, let's say a researcher wants a participant to complete two sessions of one activity, one at 8 am and the other at 9 am. If the expiry time of the first session is set to 2 hours and the participant does not complete it before 9 am, the session scheduled for 9 am will be marked as "blocked" and the associated upcoming Session Release notifications will not be triggered for that session. In another example, A researcher has set up a notification template for a study. This notification template is designed to remind participants about a session 20 hours after it begins. Imagine a participant starts one of these sessions. If they finish it quickly, say within 10 hours, Avicenna understands that this participant has already completed the session, so they don't need a notification. As a result, if a participant completes the session in less than the 20-hour reminder window, they won't get the reminder notification. ::: ### One-Off Notifications Avicenna allows you to send custom, one-off notifications to participants and other researchers of your study via In-App, Email, and SMS mediums. We refer to this as manually triggering a notification. Note that these notifications do not use a template. To create a one-off notification: - On your researcher dashboard, click on the Notifications page, and then the Notifications tab. - Click on the Send Notification button. - Specify the recipients, the mediums, and the content for each medium. (If you have more than one language added to your study, you should specify the language field too) - Hit the Send button. | ![One-Off Notification](/assets/notifications-one-off.png) | | :--------------------------------------------------------: | | One-Off Notification | :::note Keep in mind that since the Avicenna app is only used for participants, you cannot use the in-app medium to send notifications to other researchers of the study. ::: ### Data Filtering To filter your data, you can set conditions, sort, and select the columns to be shown for Notifications as necessary. If you want to learn more about this feature and how it works, please refer to the [Data Filtering page](../study-setup-and-deployment/data-filtering.md). ## Notification Settings in Avicenna Avicenna offers various notification settings to ensure both researchers and participants stay informed. Here's a breakdown of these settings: ### For Participants - Participants receive in-app notifications by default. Upon verifying their email addresses or phone numbers, they can add these additional notification methods. However, they retain the option to disable email and SMS notifications within the app. - Avicenna ensures that the in-app notification setting remains always on, but participants can adjust their other preferences: - Launch the Avicenna app. - Navigate to `Settings`. - Access `Notifications`. - Under `Mediums`, participants can specify their notification preferences. ![How participants can change notification settings on the app](/assets/notifications-settings-participant-app.png) While participants can use the Notifications page to verify their email address and phone number, they can also use the study setup section of the app. When a study is set to ask participants for a verified email address and/or phone number, participants will need to go through the verification processes. Upon successful registration in your study, a message will appear on top of the study's homepage (on the app) that reads `Your study setup is incomplete`. Participants need to click on `Continue`. Then, they will be presented with some actions to `Continue`. Then, they will be presented with some actions to take for better compliance. For more details, you can check [enrolling participants](../../getting-started/your-first-study.md#enroll-participants). ### For Researchers - Researchers have the flexibility to disable either the Email or SMS notification channels. - As a researcher, you can choose which notifications you'd like to receive: - Click on your avatar located on the top right. - Select **Notification Settings** and change the settings. | ![How researchers can change notifications settings](/assets/notifications-settings-researcher-dashboard.png) | | :-----------------------------------------------------------------------------------------------------------: | | How researchers can change notifications settings | Avicenna's Notifications ensures an easy communication process between researchers and participants. By utilizing customizable templates and various settings, researchers can keep participants informed and engaged throughout the course of a study. Whether it's automating notifications based on activity sessions or manually sending one-off notifications, Avicenna equips researchers with the tools needed for effective participant interaction. Both researchers and participants benefit from the diverse notification mediums, enhancing study compliance and fostering a more connected research environment. As you continue using Avicenna, make the most of these features to optimize communication and enhance your research outcomes. ## Troubleshooting ### Notifications are not prompted/sent If your participants informed you that they don't receive notifications, you can follow these steps to diagnose and fix the issue: 1. Check [the general steps to diagnose participation issues](participation.md#general-steps-to-diagnose-participation-issues). 2. If the notification was related to a session, [check if the session is actually created and still there](../activities/activity-sessions.md). You may want to also check the [troubleshooting section for the Sessions](../activities/activity-sessions.md#troubleshooting). 3. Check if you can find the notification under [the `Notifications` page](#notifications-log), and if yes, what the status of the notification and the mediums that were used are. 4. Check the sections below for more details based on the notification mediums. #### Email/SMS notifications 1. If it was an **email or SMS notification**, check if the participant's email address or phone number, respectively, is verified, and if they opted into these mediums. You can check [the Application State logs on Kibana](../analysis/kibana-basics/README.md#application-state) if the participant is using the mobile app. 2. If you or your participant didn't receive an email notification, you can check [this section](../../getting-started/create-a-researcher-account.md#i-didnt-receive-the-verification-email) for some tips on email delivery. #### In-app notifications (mobile apps only) 1. Make sure [the `Do Not Disturb` is disabled on the device](../analysis/kibana-basics/README.md#device-state). 2. Check if the study setup (that pink banner at the top of the study's homepage) is completed. You can check [the Application State logs on Kibana](../analysis/kibana-basics/README.md#application-state) for most of these items. - Check if the app has the permission to send notifications on the device. ##### Android app Continuing from the previous section, for the study setup on the Android app: 1. Make sure the `Survey Notifications` option is enabled in the app's settings. 2. Make sure the notifications channels `Survey-related notifications` and `Study-related notifications` are enabled in the device's settings for the app. 3. Make sure that setting alarms and reminders is allowed for the app. 4. Make sure that the battery optimization is disabled for the app. Learn more [here](../../reference/data-sources/from-smartphone/background-data-collection/README.md#battery-optimization). 5. Make sure the device-specific battery optimization settings are taken care of for the app. Learn more [here](../../reference/data-sources/from-smartphone/background-data-collection/android-battery-optimization-workarounds.md). 6. Make sure the device lets the app run reliably in the background. Learn more [here](../../reference/data-sources/from-smartphone/background-data-collection/android-background-permission-workarounds). 7. If our guides didn't work or you couldn't find any issues, check [Don't Kill My App](https://dontkillmyapp.com/). :::warning Keep in mind that [some Android manufacturers](https://dontkillmyapp.com/) prefer battery life over the proper functionality of the apps, which can make notifications unreliable; **this is not within our control**. If you couldn't find any issue using the above steps, we highly recommend you enable other mediums (email or SMS) to lower the chance of missing a notification. ::: --- sidebar_position: 9 --- # Televisit Televisit allows you and your research team to have live communication with your study participants via video, audio, or text, for purposes such as participant onboarding, adherence reminder, or troubleshooting. In this section, we will demonstrate how Televisit works in Avicenna and explain its features. ## Enabling and Accessing Televisit In order to enable this feature for your study, you need to get in touch with Avicenna’s support team via [support@avicennaresearch.com](mailto:support@avicennaresearch.com). To use Televisit, as a researcher, you can tap on the _Chat_ from the left-side panel of the Researcher Dashboard. ![Accessing Chat from the researcher dashboard](/assets/televisit-chat-researcher-dashboard.png) Participants can also find a similar button at the top right corner of their web or mobile apps. ## Chat Rooms Two types of chat rooms are designed for researchers and participants: **Direct rooms:** Direct rooms allow private conversation between only two members - one researcher with another researcher, or one researcher with a participant. ![Direct chat rooms](/assets/televisit-direct-chat-rooms.png) **Group rooms:** Group rooms contain more than two members. A group room in your study can be one of the following: - Group rooms where only the researchers are included. This group has the same name as the title of the study. In the following image, you can see the study name is _Fine Motor Skills_, and there is a chat room with the same name. - Group rooms which include all the researchers of the study and one of the participants. These groups are titled "_Participant’s name - Group_". For example, in the picture below, the room titled "_Gelare - Group"_ is the chat room for a participant named "Glare" to communicate with the researchers of the study. ![Group chat rooms](/assets/televisit-group-chat-rooms.png) Note that for privacy reasons, you cannot create a group where all participants are included. You can find all the rooms on the left side of the chat screen, categorized under _All_, _Direct_, and _Group_ tabs. Both researchers and participants can create chat rooms, but they cannot leave chat rooms. They will be removed from the rooms automatically in one of the following scenarios: - As a researcher, their access permission to the study is revoked. - As a participant, they withdraw from the study. - They choose to delete their account from Avicenna. ## Archived Chats A chat room is archived when _all_ members of the room are removed from the study for any of the reasons explained above. In this case, sending messages in that room does not make sense anymore, and Avicenna makes the room read-only and archives it. The following list explains scenarios which may lead to a room being archived: - **When a researcher is removed from the study:** - _Direct rooms_: In this case, the direct chat rooms of the researcher will be moved to the _Archived_ section. That’s because when a researcher is removed from the study, the direct rooms, whether Researcher ↔ Researcher or Researcher ↔ Participant, are not usable anymore. The room is kept under the _Archive_ for reference. - _Group rooms with multiple researchers_: No changes will happen to these rooms, nor to their messages. This means that the researchers and participants who are already in the study will see the removed researcher’s group chats. The messages will also be visible to the new researchers joining afterward. - _Group rooms with multiple researchers and one participant_: In this case, the messages will remain in the chat rooms as well. - **When a participant drops out of the study** - In such cases, the participants’ direct chats will be archived, but their group messages will still be visible to the researchers of the study. However, the messages will not be visible to the researchers joining afterward. As a researcher, you can find the _Archived_ button at the top left corner of the chat screen next to the search box. Participants have the _Archived_ tab below the search box on their mobile apps. ![Archived button on the participant app](/assets/televisit-archived-participant-chat.png) Please note that neither researchers nor participants can directly archive a chat room. Also, when a chat room is archived, you can no longer send messages or establish calls there. The following image shows an archived chat room. ![An archived chat room](/assets/televisit-archived-chat-room.png) ## List of Contacts Clicking on the _plus_ button at the right bottom of the side menu directs you to the list of contacts. This list includes all the possible direct and group rooms. Select anyone on this list to either start a new room or carry on with the previous conversation. Note that participants, as seen in the following image, only have access to the researchers, meaning that they cannot send messages or make calls with other participants of the study. ![The list of contacts on the participant app](/assets/televisit-participants-contacting-researchers.png) ## Search Boxes In the Televisit screen, you have access to two search boxes: - The first one is shown above the list of rooms. It is used for searching in the rooms that you have already taken part in. You can also look up a contact by writing their name in the search box. - The second one is shown after clicking on the _plus_ sign. Here, as a researcher, you can search within all the researchers and participants of the study. And if you are a participant, you can see and search within the researchers. ![Search boxes on the researcher chat screen](/assets/televisit-search-box-researcher-chat.png) Participants also have the same search boxes in their chat screens. ![Search boxes on the participant chat screen](/assets/televisit-search-box-participant-chat.png) ## Audio and Video Televisit You can use Avicenna Televisit for both audio and video conversation as well. These options are available in direct rooms for both researchers and participants. Avicenna protects audio and video calls with default end-to-end encryption, so no one but the intended recipient has access to the conversations. To make an audio or video call, open a direct room, and click on the phone or camera button in the top right corner of the screen. | ![Audio and video call button on the participant chat screen](/assets/televisit-audio-video-call-participant-chat.png) | ![Audio and video call button on the researcher chat screen](/assets/televisit-audio-video-call-researcher-chat.png) | | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | _**Troubleshooting:**_ Before making calls on the browser, make sure that the camera and microphone are connected to your device, and proper permissions are granted. ## Picture-in-Picture Mode One of the most important features of Avicenna Televisit is that it supports Picture-in-Picture mode. In this mode, you can minimize the video call to a corner of the screen, and continue interacting with the rest of the Avicenna mobile app or the researcher dashboard. This is useful for cases such as troubleshooting an issue for a participant, or helping them with a task they need to complete as part of the study. For example, imagine one of your study participants sends you a message in Televisit saying that she has difficulty completing a particular survey in the study. In this case, you can make a video call with the participant, and while in the call, you can minimize the video window to the corner of the screen, navigate to the section of the survey where she reported having a problem, and then walk her through the survey. ## Recording Calls Avicenna Televisit supports the recording of video calls. This feature is useful for researchers who want to keep a record of the calls for future reference, to review the conversation, or to share it with other researchers in the study. To start recording a call, click on the _Record Call_ button at the bottom of the screen. The recording will start immediately, and you can stop it by clicking on the same button. ![Recording Televisit video calls](/assets/televisit-start-recording.png) It takes a bit of time for the recording to be processed and become available for download after the recording is stopped. Once it is ready, the researcher who started the recording will receive an email with a link to download the recording. You can also find the recorded videos in the _Recordings_ section of the Chat page. There you can see the list of all the recordings along with the date and time of the recording, the users who took part in the call, and the size of the recording. You can download the recordings by clicking on their _Download_ button. ![Televisit Recordings page](/assets/televisit-recordings-page.png) Please note that only the researchers can start and stop recordings; the participants do not have access to this feature. However, the participants will be notified when the recording starts and stops. :::note Avicenna will keep the recordings for 10 days. Please ensure that you download the recordings within this time frame if you need to keep them for a longer period. ::: :::note At the moment, due to some technical limitations, the camera cannot be switched from the front to the back and vice versa, after the recording starts. ::: ## Screen Sharing > Supported in Android & iOS apps. Avicenna Televisit also supports screen sharing for the participants. This feature allows participants to share their entire screen with the researchers during a video call. This is useful for cases where the participant needs help with a task on their device, or when the researcher needs to troubleshoot an issue the participant is facing. Participants can start sharing their screen by clicking on the _Share Screen_ button at the bottom of the screen. The screen sharing will start immediately, and the participant can stop it by clicking on the same button. ![Screen sharing in Televisit as a participant](/assets/televisit-screen-sharing-participant.png) Researchers can see the participant's screen and video simultaneously. ![Seeing the shared screen in Televisit as a researcher](/assets/televisit-seeing-shared-screen-researcher.png) Additionally, the researchers can also [record the video call](#recording-calls) while the participant is sharing their screen. In this case, the participant's screen will replace the researcher's video for the duration of the screen sharing in the final recorded video. ## Online Status Researchers and participants can check the online status of each other via their Avicenna dashboards. If the person is online, a small green circle is shown at the bottom right corner of his or her profile picture. Otherwise, the circle turns gray. For example in the screenshot below, only one of the contacts is online. ![Televisit online status](/assets/televisit-online-status.png) --- sidebar_position: 10 --- # Audit Trail Avicenna Researcher Dashboard offers different aggregate reports on the data provided by each participant which you can use to monitor their adherence throughout the study. But when you find a case that you cannot explain using aggregated data, it's useful to dive deeper into the detailed interaction of the participant with their app and with your study. The data from the _Audit Trail_ can be useful in such cases. Audit Trails are secure, computer-generated, and time-stamped electronic records that capture essential information about electronic data within Avicenna. Avicenna's Audit Trail feature allows logging and tracking of modifications made by researchers or participants within a study. It provides a detailed view of data and protocol modifications, helping to identify manipulation instances, drive process improvements, and ensure accurate data collection. Valuable for numerous reasons, Audit Trails facilitate accountability, traceability, compliance audits, security monitoring, investigations, and performance analysis. Audit Trail should be used by organizations or individuals who need to maintain accurate records of actions. Audit Trails can provide information about various events and Activities depending on the audited process. Check out the [Audit Log Types and Related Messages](#audit-log-types-and-related-messages) section if you want a more comprehensive understanding of various Audit Log Types. ## Where to access Audit Trail In Avicenna, only the researchers have access to this feature. There are two ways to use the Audit Trail: 1. Through the `Audit Trail` page on the Researcher Dashboard, 2. Or using `Avicenna Kibana Integration`. Each of these approaches is explained below. ### Using the Audit Trail page on the Researcher Dashboard You can choose the target study at the top of the page. The Audit Trail table includes all events in descending order based on the "Date Time". Each row of this table shows an interaction, called an "Audit Log", which is occurred by a participant, researcher, or the System. ![Audit Trail View](/assets/audit-trail-preview.png) ### Using Kibana Integration The Avicenna Kibana link is located on the Researcher Dashboard, which takes you to Kibana's page. After entering Kibana's Discover page, you can select the _Audit Trail_ index to view all the Audit Logs for the specified period. For more information on how to use Kibana, check [Kibana](../analysis/kibana-basics/README.md). ![Kibana Discover Page](/assets/audit-trail-kibana-discover-page.png) ## Audit Log Audit Logs are the key components of the broader "Audit Trail" feature. In other words, Audit Trail is a set of Audit Logs, which are records of actions, providing evidence of user actions and events for tracking and analysis. Audit Logs might have different columns which are explained below. ### Role The role of the user who initiated the event. These roles include [_Researcher_](../terminology.md#researcher), [_Participant_](../terminology.md#participant), and the System. ### User ID A User ID (User Identification) is a unique identifier assigned to an individual. See [User ID](../terminology.md#user-id) for more information. ### Type The Audit Log Type indicates the specific type of Activity or event being recorded in the log. For example, Type might include user login and logout attempts, modifications to the Data Sources, requesting data export, or study modifications. For more technical information, see [Audit Log Types and Related Messages](#audit-log-types-and-related-messages). ### Date Time Date Time represents the date and time an event happened. ### Related Participant IDs This column is used to track the logs associated with specific participants. A subset of such logs are those related to events initiated by the system or a researcher that will affect one or more participants. For example, assume we want to see when the participant joined the study and participated in the Activity, what modifications they have made to notification settings, or whether the session is created for the participant or not. ### Related Activity IDs Each Activity is assigned a unique identifier in Avicenna, commonly called an ID. The Related Activity IDs column specifies the Activities that the event relates to. For example, if we want to see modifications made to the sessions of an Activity, we can use this column to filter the logs better. ### Message The Message column offers a log summary, allowing researchers to quickly grasp the captured log. For more details, visit [Audit Log Types and Related Messages](#audit-log-types-and-related-messages). ### Changes This column shows how many modifications have been made. Also, if you need more detail on the Changes, you can click on the Eye-shaped button. ### App Version It shows the App Version on the participant's mobile device. Check the [App Version](../terminology.md#participant-app-version) for more information. ### Reason This column shows the reason why the changes corresponding to the audit log have been applied. Currently, researchers need to specify the reasons for changes in participant data when applying those changes if they enabled [the corresponding setting](participation.md#capture-reason-for-changes-in-participants-data) for their study; other types of audit logs won't have a Reason. ## Data Filtering Using the Filter button, you can set conditions, sort, or select the columns to view the Audit Logs as required. For a detailed understanding of this feature and its operations, kindly visit the [Data Filtering page](../study-setup-and-deployment/data-filtering.md). ## Audit Log Types and Related Messages The list of Audit Log Types provides you with a comprehensive record of all the Activities and events that can occur within Avicenna. You can see these Types and example messages for each below. ### 1: Study Created A new study has been created. _Example Message_: Study 12345 created. ### 2: Study Updated Changes have been made to an existing study. _Example Message_: Study 12345 updated. ### 3: Study Deleted An existing study has been deleted. _Example Message_: Study 12345 deleted. ### 4: Study Data Source Added This message means a new data source has been added to the study. _Example Message_: Data Source "GPS" added to Study 12345. ### 5: Study Data Source Removed A data source has been removed from the study. _Example Message_: Data Source "GPS" removed from Study 12345. ### 6: Study Data Source Updated This message means that a data source has been modified or updated. _Example Message_: Data Source "GPS" updated. ### 7: Study Beacon Created A new beacon has been created in the study. _Example Message_: Beacon 2031 was created with Team ID 1324, Role ID 2413, and Subject ID 1423 for Study 12345. ### 8: Study Beacon Deleted An existing beacon has been deleted from the study. _Example Message_: Beacon 2031 deleted. ### 9: Study Translation Added A new translation for a field has been added to the study. _Example Message_: Translation added for "Description" ### 10: Study Translation Updated Changes have been made to an existing translation for a field. _Example Message_: Translation updated for "Description" ### 11: Study Export Created A new data export has been generated for the study. _Example Message_: Export 29390 created. ### 12: Study Export Deleted An existing data export has been deleted. _Example Message_: Export with ID of 29390 deleted. ### 13: Study Researcher Added A new researcher has been added to the study. _Example Message_: Researcher 68913 added to Study 12345. ### 14: Study Researcher Removed A researcher has been removed from the study. _Example Message_: Researcher 68913 removed from Study 12345. ### 15: Activity Created A new Activity has been created in the study. _Example Message_: Survey 17103 was created for Study 12345. ### 16: Activity Updated Changes have been made to an existing Activity. _Example Message_: Survey 17103 updated. ### 17: Study Language Added A new language has been added to the study. _Example Message_: Language it-IT added to Study 12345. ### 18: Study Language Removed A language has been removed from the study. _Example Message_: Language it-IT removed from Study 12345. ### 19: User Signed Up A new participant has signed up for the application. _Example Message_: User signed up. ### 20: User Signed In A participant has signed in to the application. _Example Message_: User signed in. ### 21: User Signed Out A participant has signed out of the application. _Example Message_: User signed out. ### 22: Application Opened A participant has opened the application. _Example Message_: Application opened. ### 23: Application Closed The application has been closed. _Example Message_: Application closed. ### 24: Study Update Started The mobile app started to reload the study configuration to receive the most recent updates. A study update can be initiated for the following reasons, which will be included in the report: - ID 0: Unknown - ID 1: Explicitly initiated by the user - ID 2: Retry due to a previous failed update - ID 3: App update - ID 4: Server request - ID 5: App permission change - ID 6: Time-zone change - ID 7: Joined new study - ID 8: Periodic reload _Example Message_: Study update started. Reason: "Joined new study." ### 25: Study Update Succeeded A study update for a participant's mobile app has been successful. _Example Message_: Study update finished successfully after 60 seconds. ### 26: Study Update Failed A study update for a participant's mobile app has failed. _Example Message_: Study update failed after 60 seconds. Error: "Database connection lost." ### 27: Data Sync Started Data synchronization for the mobile app has started. _Example Message_: User started data sync. ### 28: Data Sync Ended Data synchronization for the mobile app has ended. _Example Message_: User-initiated data sync finished after 60 seconds while transferring 512 KB of data. ### 29: Automatic Data Upload Finished Avicenna finished automatically uploading data for the mobile app. _Example Message_: Automatic data upload started at 2023-04-30 10:13:28 UTC and finished after 60 seconds, transferring 512 KB of data. ### 30: Timezone Changed The timezone has changed for a participant. _Example Message_: Time zone changed from America/Toronto to America/Vancouver. ### 31: Data Sync Failed Avicenna failed to upload collected data from a participant's mobile app to the servers. The reason for the failure will be included in the report which can be one of the following: - An internal error happened. - User preferences prevented Avicenna from uploading the data. For example, user preferences may require data upload on Wi-Fi only, while the user is currently on mobile Internet. - No Internet connection is available. - Incomplete data upload. Not all data were uploaded successfully due to network issues. - Another upload process was in progress. - Network problems occurred. _Example Message_: User-initiated data sync failed after 60 seconds, transferring 512 KB of data. Error: "No Internet connection available." ### 32: Automatic Data Upload Failed The mobile app failed to automatically upload data. _Example Message_: Automatic data upload started on 2023-04-30 at 10:13:28 UTC and failed after 60 seconds, transferring 512 KB of data. Error: "Database connection lost." ### 33: Automatic Data Upload Started The mobile app started to automatically upload data. _Example Message_: Automatic data upload started. ### 34: Automatic Activity Response Upload Started Uploading automatic Activity response has started for the mobile app. _Example Message_: Uploading Activity responses started. ### 35: Automatic Activity Response Upload Finished An automatic Activity response upload has been completed for the mobile app. _Example Message_: Uploading Activity responses started on 2023-04-30 at 10:13:28 UTC and finished after 60 seconds. ### 36: Automatic Activity Response Upload Failed An automatic Activity response upload has failed for the mobile app. _Example Message_: Uploading Activity responses started at 2023-04-30 10:13:28 UTC and failed after 60 seconds. Error: "Database connection lost." ### 37: Activity Opened A participant has opened an Activity. _Example Message_: Activity ID 17103 opened. ### 38: Activity Closed A participant closed an Activity, without finishing it. Note that if a participant closes an Activity, they can still come back and continue it later. _Example Message_: Activity ID 17103 closed. ### 39: Activity Finished An Activity session is concluded, either because the participant completed responding to the Activity, it was expired, or the participant decided to cancel the Activity. _Example Message_: Activity ID 17103 finished. ### 40: Beacon Activity Triggered An Activity with a Proximity TL has been triggered. _Example Message_: Activity ID 17103 was issued because of the proximity to the beacon with Team 1324, Role 2413, Subject 1423, first seen at 2023-04-30 10:21:13 UTC. ### 41: Notification Prompted A notification has been prompted to the mobile app. _Example Message_: Notification Template 35880 issued for session 7b5840df-ed09-4449-b0bc-81567db3ac85 of Activity 17103. ### 42: Notifications Status Updated The status of an in-app notification for the mobile app has been updated. _Example Message_: App updated the status of its in-app notifications to the following. Each entry includes: template id, session uuid, time, and status, respectively: #1953, 3117b9a7-d771-406f-9645-810f43a63399, 2023-05-10 09:09:16 UTC, Scheduled by OS ### 43: Available Notifications Changed The list of notifications for the current participant has changed. If a notification is added, it shows an issue was detected by the Avicenna app and a notification was shown to the participant. If a notification is removed, it shows the previously reported issue was resolved and the associated notification is removed. - ID 1: Location permission not granted. - ID 2: GPS is disabled. - ID 3: Wi-Fi is disabled. - ID 4: Bluetooth is disabled. - ID 5: Audio recording permission is not granted. - ID 6: Browsing history plug-in is not available. - ID 8: App usage access permission is not granted. - ID 13: Phone validation is due. - ID 14: Email validation is due. - ID 15: Background GPS permission is not granted. - ID 16: Notification permission is not granted. - ID 17: Foreground GPS permission is not granted. - ID 18: Disable battery optimization for the app. - ID 19: App update is available. - ID 20: Physical Activity Recognition permission is not granted. - ID 21: Persistent banner notification is not enabled. - ID 22: Apple HealthKit permissions are not granted. - ID 23: Apple SensorsKit permissions are not granted. - ID 24: Disable device-specific battery optimization for the app. - ID 30: Grant exact alarm manager permission. _Example Message_: Notification "GPS is disabled" is Added. ### 44: Study Settings Changed A participant modified the app settings. The report includes current app settings. The settings which are modified can be one of the following: - ID 1: Upload via Wifi Only. - ID 2: Upload when plugged. - ID 3: Rapid upload. - ID 4: Sticky notification (Android only). - ID 5: Use an alarm clock for survey notifications (Android only) - ID 6: Enable/Disable Notification Medium Email - ID 7: Enable/Disable Notification Medium SMS _Example Message_: User enabled the "Upload via Wifi Only" setting. ### 45: Data Source Status Changed A data source status has been updated by a participant. _Example Message_: User disabled “GPS” data source. ### 46: Data Collection Status Changed The status of data collection has been changed by a participant. _Example Message_: User paused data collection. Data collection will resume on 2019-03-22 06:17:48 UTC. ### 47: Notification Sent A notification has been sent. _Example Message_: Server sent a notification to the user via "email" saying "Your session has expired." ### 48: Notification Not Sent A notification failed to be sent. _Example Message_: Server failed to send a notification to the user via "email" saying "Your study data export failed." Error: "Database connection lost." ### 49: Beacon Was Observed A participant's smartphone observed a given Bluetooth beacon registered for this study. _Example Message_: Beacon with Team ID 1, Role ID 1, and Subject ID 2 was observed from 2019-03-22 06:17:48 UTC to 2019-03-22 06:27:48 UTC. ### 50: Study Reloaded A study has been reloaded. _Example Message_: Study reloaded for Participant(s) with ID of 68576. ### 51: Activity Deleted An Activity has been deleted. _Example Message_: Survey 17103 deleted. ### 52: Registration Created A Registration has been created. _Example Message_: Participant 68576 registered on Study 12345. ### 53: Registration Dropped A Registration has been dropped. _Example Message_: Participant(s) 68576 dropped from Study 12345. ### 54: Registration Deleted A Registration has been deleted. _Example Message_: Registration(s) 58323 deleted. ### 55: Registration Participation Period Updated The Participation Period for registration has been updated. _Example Message_: Participation period updated for 68576. ### 56: Registration Participation Label Updated The Participation Label for registration has been updated. _Example Message_: Participant(s) 68576 label updated. ### 57: Registration Participant Quit A participant has quit the study. _Example Message_: Participant 68576 quit the study 12345. ### 58: Registration Rejoin A participant has rejoined a study. _Example Message_: Participant 68576 re-joined Study 12345. ### 59: Notification Created A notification has been created. _Example Message_: Notification 125241437 created 35880 on Study 12345. ### 60: Notification Deleted A notification has been deleted. _Example Message_: Notification 125241437 deleted. ### 61: Notification Template Created A Notification Template has been created. _Example Message_: Notification Template 35880 created. ### 62: Notification Template Updated A Notification Template has been updated. _Example Message_: Notification Template 35880 updated. ### 63: Notification Template Deleted A Notification Template has been deleted. _Example Message_: Notification Template 35880 deleted. ### 64: Activity Duplicated An Activity has been duplicated. _Example Message_: Survey 12345 duplicated with ID of 54321. ### 65: Activity Moved An Activity has been moved to another study. _Example Message_: Stroop 17103 moved from Study 12345 to Study 54321. ### 66: Activity Session Created An Activity session has been created. _Example Message_: Session(s) created for study 12345. ### 67: Activity Session Updated An Activity session has been updated. _Example Message_: Session(s) updated for study 12345. ### 68: Activity Session Deleted An Activity session has been deleted. _Example Message_: Session(s) deleted from study 12345. ### 70: Registration Read A Registration has been read by the participant. _Example Message_: Participant read their registration status. ### 71: Garmin Created A Garmin device has been added. _Example Message_: Garmin device created for 58850. ### 72: Garmin Updated Garmin-related settings have been updated. _Example Message_: Garmin settings updated. ### 73: Garmin Connected A Garmin device has been connected. _Example Message_: Garmin device connected. ### 74: Garmin Disconnected A Garmin device has been disconnected. _Example Message_: Garmin device disconnected. ### 75: Garmin Permission Updated Garmin-related permissions have been updated. _Example Message_: Garmin device permission changed. ### 76: System Message Created A system message has been created. _Example Message_: System message for "Reload Studies" created. ### 77: System Message Deleted A system message has been deleted. _Example Message_: System message for "Reload Studies" deleted. ### 78: Study Wiped A study has been wiped. _Example Message_: Clear data for study 12345. ### 79: Study Invitation Created A study invitation has been created. _Example Message_: Researcher invited "participant@gmail.com" to Study 12345. ### 80: Study Invitation Re-sent A study invitation has been re-sent. _Example Message_: Researcher resent invitation for "participant@gmail.com" to Study 12345. ### 81: Study Invitation Deleted A study invitation has been revoked. _Example Message_: Researcher revoked the "participant@gmail.com" invitation to Study 12345. ### 83: User Created A user has been created. _Example Message_: New user created. ### 84: User Updated A user's account information has been modified. _Example Message_: User updated. ### 85: User Deleted A user's account has been deleted from the system. _Example Message_: User deleted. ### 86: Demographic Info Created New demographic information has been created for a user profile. _Example Message_: Demographic info created. ### 87: Demographic Info Updated A piece of existing demographic information for a user has been modified. _Example Message_: Demographic info updated. ### 88: Demographic Info Deleted A piece of demographic information has been deleted from a user's profile. _Example Message_: Demographic info deleted. ### 89: Audit Trail Page A researcher has accessed the Audit Trail page. _Example Message_: Researcher opened the Audit Trail page. ### 90: Activity Page A researcher has visited the Activity page. _Example Message_: Researcher opened the Activities page. ### 91: Data Sources Page A researcher has accessed the Data Sources page. _Example Message_: Researcher opened the Data Sources page. ### 92: Basics Page A researcher has visited the Basics page. _Example Message_: Researcher opened the Basics page. ### 93: Beacons Mapping Page A researcher has accessed the Beacons Mapping page. _Example Message_: Researcher opened the Beacons Mapping page. ### 94: Notification Templates Page A researcher has visited the Notification Templates page. _Example Message_: Researcher opened the Notification Templates page. ### 95: Notifications Page A researcher has accessed the Notifications page. _Example Message_: Researcher opened the Notifications page. ### 96: Participation Page A researcher has visited the Participation page. _Example Message_: Researcher opened the Participation page. ### 97: Pending Invitations Page A researcher has accessed the Pending Invitations page. _Example Message_: Researcher opened the Pending Invitations page. ### 98: Activity Sessions Page A researcher has visited the Activity Sessions page. _Example Message_: Researcher opened the Activity Sessions page. ### 99: Survey Responses Page A researcher has accessed the Survey responses page. _Example Message_: Researcher opened the Survey Responses page. ### 100: Data Export Page A researcher has visited the Data Export page. _Example Message_: Researcher opened the Data Export page. ### 101: Survey Content Created Contents have been created for a new Survey. _Example Message_: Created a new Survey content 17103. ### 102: Survey Content Updated An existing Survey content has been modified. _Example Message_: Updated Survey content 17103. ### 103: Survey Content Deleted A Survey content has been deleted. _Example Message_: Deleted Survey content 17103. ### 104: Activity Released An Activity has been released to the participants. _Example Message_: Survey 17103 released. ### 105: Activity Published An Activity has been published for the participants. _Example Message_: Survey 17103 published. ### 106: Notification Updated A notification has been modified. _Example Message_: Notification 125241437 updated. ### 108: Data Collection Cycle Did Not Start A data collection cycle failed to initiate. _Example Message_: The data collection cycle did not start. Reason: "Lost network connection" ### 109: Data Collection Cycle Deviation Detected Anomalies were detected within a data collection cycle. _Example Message_: Data collection cycle deviation detected. Duty cycle first execution time: 08:00:00 UTC, Duty cycle last execution time: 16:00:00 UTC, Duty cycle actual count: 24, Duty cycle deviation count: 2, Duty cycle expected count: 22 ### 110: Application Terminated The application has been shut down. _Example Message_: Application terminated. ### 123: TUD Session Created A new Time User-Defined (TUD) session has been created. _Example Message_: TUD TL Session created. ### 124: TUD Session Rescheduled or Deleted A TUD session has been rescheduled or deleted. _Example Message_: TUD TL Session rescheduled or deleted. ### 125: TUD Session Deleted A TUD session has been deleted from the system. _Example Message_: TUD TL Session deleted. ### 126: Time Session Rescheduled or Deleted A Time session has been rescheduled or deleted. _Example Message_: Time TL Session rescheduled or deleted. ### 127: Notification State Changed Notification settings have been changed for a participant. _Example Message_: User "disabled" notifications. ### 128: Notification Channel State Changed Settings for a Notification Channel have been updated for a participant. Notification channels include Survey-related and Study-related channels. _Example Message_: User "enabled" "Survey-related" notification channel. ### 129: Session Read A user has opened and viewed a session. _Example Message_: Session fetched. ### 130: Data Collection Failed The mobile app failed to collect data for a data source. The reason for the failure will be included in the report which can be one of the following: - ID 0: Unknown - ID 1: Sensor not supported - ID 2: Sensor disabled - ID 3: Permission not granted - ID 4: Value not provided Also, the error message might be included which can be one of the following: - Sensor {sensor name} does not exist on the device. - Value not provided for sensor {sensor name}. - Microphone permission not granted. User notified. - Failed to start audio recording. - User notified about app usage permission. - Bluetooth adapter not found. - GPS adapter not found. - The Beacons info is empty. - Bluetooth adapter is not available. - Bluetooth permission is not granted. User notified. - Bluetooth is disabled. User notified. - GPS permission is not granted. User notified. - GPS is disabled for Bluetooth discovery. User notified. - Bluetooth records are empty. - GPS disabled. User notified. - The location manager is not available. - GPS and Wifi are disabled. - GPS and Wifi are empty. - Play service is not available. - MBAR permission not granted. User notified. - Update Connection failed. - Failed to connect for an update. Code: {status code}. - Update Connection canceled. - MBAR Records are empty. - The sensor does not exist on the device. - WiFi disabled. User notified. - Could not acquire Wifi Manager. - The Wifi scan result is empty. - Stream {Data Source name} is not active for study {study id}. _Example Message_: The data collection for data source "GPS" failed. Reason: "Permission not granted", error message: "GPS permission is not granted. User notified." ### 131: Study Site Added When the user adds a new site to the study. _Example Message_: Site 123 added. ### 132: Study Site Edited When the user edits a study site. _Example Message_: Site 456 edited. ### 133: Study Site Removed When the user removes a study site. _Example Message_: Site 789 removed. ### 134: Participant Site Changed When the user changes one or more participants' sites. _Example Message_: Site changed to 2 for participant(s). ### 135: Study License Upgrade Requested When the user requests an upgrade on the study license. _Example Message_: Study license upgrade requested. ### 136: Researchers Page Opened When the user opens the "Researchers" page. _Example Message_: Researcher opened the Researchers page. ### 137: Study Ownership Transferred When the current study owner transfers the ownership to another researcher. _Example Message_: Study ownership transferred to researcher 1234. ### 138: Researcher Promoted to Permission Manager When a researcher promotes another researcher to Permission Manager. _Example Message_: Researcher 1234 promoted to Permission Manager. ### 139: Researcher Demoted from Permission Manager When a researcher demotes another researcher from the Permission Manager. _Example Message_: Researcher 123 demoted from Permission Manager. ### 140: Roles and/or Permissions Changed When roles and/or permissions for a user changes. _Example Message_: Roles and/or permissions changed for researcher 1234. ### 141: Site Role Created When the user creates a new site role. _Example Message_: Site role "Manager" created. ### 142: Site Role Deleted When the user deletes a site role. _Example Message_: Site role "Editor" deleted. ### 143: Site Role Edited When the user edits a site role. _Example Message_: Site role "Admin" edited. --- sidebar_position: 11 --- # Data Filtering Searching within your study's data is an important part of your research. Avicenna provides you with a powerful filtering tool that you can use to query your data. Currently, this data filtering is available on the following pages: - Notifications - Participation - Audit Trail - Activity Responses To access this feature, while you are at one of the above pages, simply click on the `Filter` dropdown, and choose `Manage Filters`. In the `Manage Filters` dialog, you can see Avicenna's default data filter. This is the filter that is applied to your data by default. You cannot change this filter, rename it, or delete it. However, you can create a new Filter and apply your conditions to it. Start by clicking on the `Create New Filter` to create a new one. On the right side, you will see three tabs, `Conditions`, `Sorts`, and `Columns`, as shown in the image below: ![Data Filtering Elements](/assets/data-filtering-elements.png) You can use these tabs to create the data report specific to your needs. Below, we explain each of these tabs. ## Conditions A condition defines what data should be included in your search results, based on the selected category, fields, operator, and values. You can add multiple conditions to your filter and even group them together to make your search query more complex. Let's see what are different parts of a condition, and how you can use them to build your filter. ![Main parts of Conditions tab](/assets/data-filtering-conditions.png) 1. **Category:** Category is used to group relevant fields together. Based on the page you are visiting on the Researcher Dashboard, you will see different categories. For example, when you are on the Activity Responses page, you will see a list of categories like _Activity Response_, _Participant_, _Session_, and so on. ![Category as a part of Conditions tab](/assets/data-filtering-conditions-category.png) 2. **Field:** the second drop-down allows you to choose the data field that you want to use in your filter, for example, _Avicenna ID_, _Label_, or _Status_. ![Field as a part of Conditions tab](/assets/data-filtering-conditions-field.png) 3. **Operator:** The operator is self-explanatory, and determines the relationship between your field and the value: ![Operator as a part of Conditions tab](/assets/data-filtering-conditions-operator.png) 4. **Value:** This is the value you want to use in this filter, and can be either a single- or multi-select list, a text, a number, or a date. Each condition has a menu on the right side, and a three-line drag-handle next to it. The menu provides the options to delete or duplicate the condition. The drag-handle allows you to rearrange the order of the conditions. This matters if you consider the priority of your conditions. ![Delete and Duplicate options](/assets/data-filtering-delete-duplicate-condition.png) ### Adding Multiple Conditions and Condition Group You can have more than one condition in your filter, as shown in the image below: ![Adding Multiple Conditions](/assets/data-filtering-multiple-conditions.png) All conditions are either `AND` together or `OR` together. If you want to mix `AND` and `OR` in your query, you will need to group your conditions. As an example, assume you want to query all active participants in your study for whom either at least one email or at least one SMS notification has failed. In this case, you need to define three filters and group them appropriately, as explained below: 1. Click on **Add Condition** and build the first condition. Then select _Participant_ as Category, _Status_ as Field, _is equal to_ for the Operator, and _Active_ for the Value. 1. Click on **Add Condition Group** and make sure that **And** is selected. 1. Click **Add Condition** inside the new group to build the second condition. For this one, choose _Notification_ for the Category, _Email Status_ for the Field, _is equal to_ for the Operator and _Failed_ for the Value. 1. Click **Add Condition** inside the new group again and build the final 1. condition. Make sure that **Or** is selected. For this one, you need to select _Notification_ for the Category, _SMS Status_ for the Field, _is equal to_ for the Operator and _Failed_ for the Value. 1. Press **Apply**. ![Adding Condition Group in the Data Filtering](/assets/data-filtering-conditions-group.png) ### Aggregation In certain cases, you may want to aggregate all values of a field and use that in your filter, rather than using each individual value. For example, you may be interested in the number of completed sessions, or minimum response to a survey question. This can be achieved using the `Aggregate` dropdown for each filter. Avicenna supports the following aggregation options: Count, Distinct Count, Minimum, Maximum, and Average. Each of these options will be explained below. Please note that the aggregation option is only available if the data you are filtering contains more than one record of the data you are using in your condition. For example, each survey session has only one status. So if you are filtering survey sessions based on status, you cannot use aggregation. But you can send multiple notifications for each session, and therefore each session can have more than one notification. So you can use aggregation when using Notification as a condition in filtering sessions. As another example, each participant very likely will have more than one survey session. So if you are filtering participants based on their sessions, the system will present you with the aggregation option. ## Sort You can sort your data based on one or more fields. To choose a field for sorting, in the **Sort** tab, click on **+ Add Sort**, and then choose your field. You can also choose whether the sort should be done in ascending or descending order. ![Adding a Sort](/assets/data-filtering-sort.png) You can also use the `X` icon to remove a field from sorting. You can rearrange the fields you have chosen for sorting by dragging the two-line icon on the right side of each field. You can also use the `Delete All Sorts` option to remove all sorting criteria you had specified. ![Using multiple Sorts](/assets/data-filtering-multiple-sorts.png) ## Columns The `Columns` tab lets you customize and choose which columns of the data should be retrieved and displayed. ![Columns Tab for Data Filtering](/assets/data-filtering-columns.png) Columns can be easily rearranged with drag-and-drop using the horizontal lines. You can revert the selected columns in a filter back to their default settings by clicking on `Reset to Default` under the Columns tab. ## Managing Filters To manage your filter, click on the menu on its right side. This will give you the option to duplicate your filter, export its result as a CSV file, set it as default, rename, or delete it: ![Modifying filters in Manage Filters dialog](/assets/data-filtering-managing-filters.png) ### Exporting Filter Results You can export the filtered data in CSV format for further analysis. Here are two ways to do so: 1. **Without Applying Filter**: In `Manage Filters`, select `Export Results as CSV` for a chosen filter in the 3-dots menu to export and download the data. ![Export data without applying filter](/assets/data-filtering-export-data-in-manage-filters-dialog.png) 2. **After Applying Filter**: Next to the `Filters` drop-down, use `Export as CSV` button to export and download the data as per the currently applied filter. ![Export data after applting filter](/assets/data-filtering-export-data-after-applying-filter.png) --- sidebar_position: 12 --- # Study Dropout Participants may decide to withdraw from your study at any time. Here we explain how participants can do so using the Avicenna app, and how you can get a report on those who dropped out. Further, we show how you can set up a Dropout survey to be asked of participants before they leave the study, in order to capture the underlying reasons. ## Participant Dropout Participants can drop out of a study using [the Avicenna app](enrollment.md#avicenna-participant-app). To do so, they should open the Avicenna app, navigate to `Settings → My Studies`, select your study from the list, and from the `About Study` page, tap on the `Drop Out of The Study` button. ![Avicenna study about page in Android](/assets/avicenna-enrollment-study-home-page-android.png) When the button is tapped, the app asks the participant to confirm their decision. If they choose `Yes`, first Avicenna checks if your study has any [Dropout Survey](study-dropout.md#dropout-survey). If yes, the participant is asked to complete the Dropout Survey. When the participant completes or cancels the survey, or if you have not set any Dropout Survey for your study, Avicenna continues with the dropout process and withdraws the participant from the study. :::info When a participant drops out of your study, or [you drop out a participant,](../study-setup-and-deployment/participation.md#drop-from-study) the data collection is stopped immediately, but all data they have provided up to that point, and their participation record, will be retained. So you will still see the participant ID in the [list of your participants](participation.md). Their record will be marked as _Dropped_. ::: The participant can rejoin your study later. If they do, Avicenna will use their existing record. If they rejoin before their participation was originally supposed to end, they can continue until that time. If they try to rejoin after their original end time, they will get an error message saying they have completed their participation in your study. ### Dropout Survey You can create a **Dropout Survey** to get a report on why the participant decided to drop out of your study. This survey will be shown immediately before the participant is dropped out of your study. To add a Dropout Survey, click on the **Activities** page. On the Activities page, click on the `Create New Activity` button. Then click on Droput survey. On the `Content` page, add the questions you want to ask the participants before they drop out of your study. Then move to the `Preview and Publish` tab and [publish your survey](../surveys/README.md#publish-surveys). You can [view the responses](../surveys/view-responses.md) to the Dropout Survey on the Activity Responses page. --- sidebar_position: 13 --- # Account Deletion In what follows, we will demonstrate how participants can delete their Avicenna account and any data associated with it by following a number of easy steps. We will also show how researchers are notified of their participants’ account deletion. ## How to Permanently Delete Your Participant Account The following steps describe the process using the Avicenna participant web app, but the same actions can be performed in our Android and iOS mobile applications. 1. Open [the web app](https://avicennaresearch.com/app/) and make sure you are logged in. Then, go to the **Settings** page. ![Settings Button on the Avicenna App](/assets/participant-web-app-settings-button.png) 2. Scroll down and click on **Delete Account**. ![Delete Account Menu Item](/assets/participant-web-app-delete-account-button.png) 3. A message shows up reading _"Your account with any associated data will be deleted in 14 days."_. The displayed message also indicates that the deletion request can be revoked within the upcoming two weeks. ![Account Deletion First Confirmation](/assets/participant-web-app-delete-account-first-confirmation.png) 4. After clicking on **Continue**, you will be taken to the **Account Deletion** **Confirmation** page where you should enter your **Password** and choose **Confirm** to complete the deletion request. ![Account Deletion Second Confirmation](/assets/participant-web-app-delete-account-password-confirmation.png) 5. This will be followed by a dialog that confirms your account deletion has been initiated. At this point, your account and all the collected data associated with it will be completely deleted in 14 days. ![Account Deletion Initiated](/assets/participant-web-app-delete-account-initiated.png) ## Revoke the Account Deletion Request You can revoke your deletion request by logging into your Avicenna account within the next 14 days after initiating the deletion request. If you do so, you will see a message informing you that the account deletion has been revoked. ![Your Account Restored](/assets/participant-web-app-delete-account-revoked.png) ## Sign Up Again After your account has been deleted, you can sign up again with the same email address or use that email address in another account as long as it hasn't been taken by another user on Avicenna. ## We Can't Delete Your Account For security reasons, we can't delete an account for you. You'll need to be able to log in to your account to request deletion. If you can't remember your password, you should be able to reset it. ## How Researchers are Notified of the Participant's Account Deletion Once a participant requests their account to be deleted, all researchers in the participant's studies are notified via email. This provides the researchers with the option to reach out to the participant and either perform a "withdrawal survey", or convince them to change their mind. ![Email Notifying Researchers of Participants' Account Deletion Request](/assets/account-deletion-requested-email-notification.png) If the participant revokes their request, this decision is also emailed to the study researchers. ![Email Notifying Researchers of Participants' Account Deletion Revocation](/assets/account-deletion-revoked-email-notification.png) --- sidebar_position: 14 --- # Branding Avicenna allows you to modify the look and feel of the mobile and web-based app to match the theme of your study. To do so, all you have to do is pick a background image for your study and set it either while creating the study (as described [here](create-a-new-study.md#study-background)), or later on through the _Basics_ page. Avicenna will use this image throughout the application. For example, when a participant is invited to join your study and opens the Avicenna app for the first time, the home screen will be branded for your study, as shown in the image below: | | | | :-----------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------: | | ![Using Study Background for App Branding in Android](/assets/avicenna-branding-login-and-registration-android.png) | ![Using Study Background for App Branding in iPhone](/assets/avicenna-branding-login-and-registration-ios.png) | | Android | iPhone | Further, throughout the app, your chosen background will be shown: | | | | :----------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------: | | ![Using Study Background for App Branding in Android](/assets/avicenna-branding-home-screen-android-resized-1.png) | ![Using Study Background for App Branding in iPhone](/assets/avicenna-branding-home-screen-ios-resized-1.png) | | Android | iPhone | While this is very helpful for participants who potentially are familiar with the name and brand of your study and your institution, the name, logo, and introduction screen of the app remain to belong to Avicenna. So the participants still should be instructed to search for the "Avicenna" app. If you want the app to be fully branded for your study, including the name of the app in Apple's App Store and Google's Play Store, the logo, and other sections of the app, you can request the full customization of the app. The image below shows one of the applications that uses a fully customized name and logo, though it's powered by Avicenna, and therefore it benefits from all the features Avicenna offers: | | | | :-----------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------: | | ![Customized Apps in Android Powered by Avicenna](/assets/avicenna-branding-customized-app-android.png) | ![Customized Apps in iPhone Powered by Avicenna](/assets/avicenna-branding-customized-app-ios.png) | | Android | iPhone | If your study has customized apps, Avicenna will show and redirect participants to your apps instead of Avicenna's apps, wherever necessary. One example would be when the participants open your study's [registration URL](enrollment.md#using-registration-url). Customized apps can be published in one of these two modes: - Single-Study mode: The app can only be used for a single study. Participants will be enrolled in the study automatically when they log in to the app and they won't be able to join any other study. - Multi-Study mode: The app can be used for any number of studies. Participants can join multiple studies using the app just like what the main Avicenna app supports. Please note, customizing the apps is not currently available from the Researcher Dashboard due to the technical limitations. If you are interested, please contact [Avicenna Support](mailto:support@avicennaresearch.com) for more details on this option. ## Troubleshooting ### Participants can't have two Avicenna Android apps installed simultaneously Due to Android limitations and how apps published by Avicenna are developed, participants cannot have two Avicenna apps (e.g., the main Avicenna app and a custom app) installed simultaneously on their Android devices. To ensure participants can join and continue participating in multiple studies, you can go with one of these options: 1. Use the main Avicenna app, which supports participation in multiple studies. 2. Request a custom app with the multi-study mode, which allows participants to join multiple studies through the custom app. # Multi-Site Studies Multi-site allows studies to conduct participant recruitment across various regions, leading to more diversified research outcomes. In this article, we will guide you through the functionalities for managing your study across multiple sites, such as viewing the list of study sites, adding a new site, editing site details, and more. In the context of the multi-site, all researchers associated with a study are given equal access to manage all its sites. This ensures effective collaboration and information sharing among the research team. :::note In the current version of the `Multi-site`, all study sites follow the same protocol. ::: Now, let's dive into a set of functionalities for managing your study across multiple sites: ## Viewing the List of Study Sites On the `Basics` page, scroll down to the `Sites` section. Here, you'll find a list of all your study's sites, with each site displaying a unique ID, Name, and Location. The list is sorted in ascending order based on the site IDs, but you can sort it alphabetically according to any column. ![Site section on Basics page](/assets/multi-site-site-section.png) By default, all studies have only one site called `Site 1`. If your study does not use multiple sites, you can simply keep `Site 1` as the only site. In this case, you will not see the site selector option on any of the researcher dashboard pages. ## Adding a Site In the `Sites` section of the `Basics` page, click on the `Add Site` button to add a new site. This action will trigger a dialog box where you need to specify the `Name` and `Location` of the new site. After clicking `Add`, your new site will be included in the study and appear at the end of the sites list. ## Editing a Site Each site in your list has a menu (represented by three vertical dots) beside it. You can click on the `Edit` option under this menu to edit the site's details. In the `Edit Site` dialog, you can update the `Name` and/or `Location` of the site. Don't forget to click `Save` to confirm the changes. ![Edit Site dialog](/assets/multi-site-edit-site-dialog.png) ## Removing a Site The menu next to each site also allows you to remove a site. When you want to remove a site, a `Remove Confirmation` dialog will prompt you to affirm your action. Note that you can't remove a site that currently has associated participants (either invited or joined). ![Remove Confirmation dialog](/assets/multi-site-remove-confitmation-dialog.png) :::info Keep in mind that you cannot remove the default site, named `Site 1`, from your study. ::: ## Switching Between Sites If your study involves multiple sites, you can use the `Site Selector` to choose which site's data to view or export. This selector is available at the top of every data-related page (like `Beacons Mapping`, `Notifications`, `Participation`, `Pending Invitations`, `Sessions`, `Audit Trail`, `Survey Responses`, or `Data Export`). :::info The system will remember your selection until you log out. Also, any search query you conduct will be done within the data of the selected site. ::: # Roles and Permissions Sometimes you may need to assign specific permissions to each of the contributing researchers in your study based on their responsibilities. For instance, you may need to assign the _Data Manager_ role to one of your researchers and grant them permission to access, view, and export data for further investigation. In another case, you may need to assign another researcher the _Recruiter_ role with permission to enroll new participants, view participant information, and modify their enrolment data, but not be able to access their study data. Our platform allows you to define and modify the roles and permissions for each one of your researchers inside the `Researchers` page on your researcher dashboard. In the following sections, we will discuss how you can create a role, assign it to a researcher and modify their permissions, so each of the researchers has specific permissions based on their roles. Let's start with how you can manage roles for your study: ## 1. Managing Study Roles Within the `Roles` tab of the `Researchers` page on your dashboard, you can create, edit, delete, and view roles. This tab also provides a list of all roles already defined, their names, and associated permissions. When you create a role inside the `Roles` tab, you are defining a role and its permissions throughout your study. As a result, you will not be able to select a site in the `Create a New Role` dialog. To modify the access of a role for a specific site, please see the [Permission Adjustment](#23-adjusting-researcher-permissions) section. After creating a role, you can assign it to researchers on the `Researchers` tab, and make further adjustments as necessary. Here are some actions you can perform inside the `Roles` tab: ### 1.1 Creating a New Role To create a new role with specific permissions: - Open the `Researchers` page on your dashboard. - Navigate to the `Roles` tab. - Click on `Create New Role`. - Enter a unique name for the role, limited to 100 characters. - Select the desired permissions for this role. - Click `Create` to complete the role creation. ![Creating a New Role](/assets/roles-and-permissions-creating-new-role.png) ### 1.2 Editing an Existing Role To modify an existing role: - Go to the `Roles` tab and find the role to be modified. - Click the 3 dots menu and select `Edit` to change the role`s name and permissions. - Save the changes to update the role. Doing so will immediately change the permissions for all researchers with this role. ### 1.3 Deleting a Role To delete a role: - In the `Roles` tab, locate the role you need to delete. - Click on `Delete` in the 3 dots menu and confirm your decision to remove the role. Note that removing a role will revoke all of its permissions from the researchers who were assigned this role. ### 1.4 Pre-defined Roles in Avicenna In addition to the roles that you can define in the Roles tab, there are some pre-defined roles. #### 1.4.1 Study Owner As the name suggests, the study owner is a person who owns the study and has full control over all of it. Each study can have only one owner, and by default, the person who has created the study is the owner. For example, the study owner is the **only** person who has access to and can control the study license information. Also, she/he is the main point of contact for any outreach from Avicenna. The study owner can change the permission and roles of all the researchers even themselves. They can also promote/demote a researcher to the [Permission Manager](#142-permission-manager) role or even make them the study owner. To assign the study ownership to another researcher: - As the current study owner, go to the Researchers tab. - Click on the 3 dots menu next to the researcher you want to transfer the ownership to. - Verify your identity and confirm the transfer to complete the ownership change. Please note that in this case, the ownership will be removed from your account and transferred to the chosen researcher. #### 1.4.2 Permission Manager Permission Manager is another pre-defined role that can be given to a researcher by the study owner or another permission manager. Researchers with the Permission Manager role can modify the roles and permissions of any researcher in the study, including themselves, and excluding the study owner. They can also promote/demote other researchers to/from permission managers. By default, there are no permission managers when creating a new study. The study owner can promote any researcher to be the permission manager. To promote/demote a researcher to have/from having this role, follow these steps: - In the `Researchers` tab, click on the 3 dots menu next to the researcher`s name. - Select `Promote to/Demote from Permission Manager` and confirm. ## 2. Managing Researchers and Permissions In the **Researchers** tab, you can invite new researchers to your study, add or remove roles to each researcher, adjust their roles and customize them, or revoke their access from the study completely. Let's explain these actions in more detail: ### 2.1 Adding Researchers to a Study To add new researchers for expanding and collaborating within the research team: - Open the `Researchers` page and move on to the `Researchers` tab. - Click `Add New Researcher` and enter the researcher`s email address. Note that this new person should already be registered in Avicenna as a [Researcher](../terminology#researcher) and also should have verified their email address. - Assign appropriate roles to define their access and capabilities. - Confirm to finalize the addition of the researcher to the study. ![Adding a New Researcher](/assets/roles-and-permissions-adding-new-researcher.png) ### 2.2 Removing Researchers from a Study To remove a researcher: - Navigate to the `Researchers` tab. - Click on the 3 dots menu and choose `Remove` - Confirm the removal to complete the process. ![Removing a Researcher from a Study](/assets/roles-and-permissions-removing-researcher-from-study.png) ### 2.3 Adjusting Researcher Permissions You can adjust the permission of a researcher and/or assign them a new role in the Researchers tab. ![Adjusting Researcher Permissions](/assets/roles-and-permissions-adjusting-researcher-permissions.png) When modifying the permissions of a given researcher, you can specify the following: - Site: Using this dropdown, you can control whether the researchers' permission is applicable to all sites, or only a specific site. Note that you cannot give access to multiple sites to the researcher. It should be either just one site or all sites. - Roles: Using this dropdown you can assign researchers one or multiple roles. The union of the permissions for the selected roles will be chosen for the researcher. :::note Selecting a predefined role from the `Roles` dropdown will overwrite any existing permissions with the permissions defined for that researcher. These roles and their permissions can be managed in the [Roles](#1-managing-study-roles) tab. ::: - Study Protocols and Study Data: In this section, you can modify permissions one by one only for this researcher. Changes made here will override the permissions defined in the assigned roles. To modify the researchers' permissions follow these steps: - In the `Researchers` tab, click on the 3 dots menu and - Select `Adjust Roles & Permissions`. - Modify their permissions. - Save the changes to update their access levels. There are 3 options for each of the permissions inside the Study Protocol and Study Data sections: - **Full** which allows them to not only view the data but change them, export them, or modify them. For instance, they can generate new sessions for participants or export their responses to a specific activity. - **View** which allows them to only view the data in the related section. Following the example above, researchers with this option can only view each session and its status, but they can not export the data. - **None** which removes any access to the study protocol or data. Note that when the permission is set to None, the related page to those permissions will not be shown for the researcher. For example, if the Notification Templates permission is set to None, then the Notifications page will not be shown in the researcher dashboard. Also, if changing permission is overwriting a permission set defined by a role, a warning will be displayed next to the permission with a message. ![Permission Overwrite Warning](/assets/roles-and-permissions-permission-overwrite-warning.png) #### Permissions Hierarchy and Dependencies Within the `Adjust Roles & Permissions` interface, permissions are interdependent and hierarchically structured, which affects the availability and scope of permissions adjustments: - **Participation Dependence**: The ability to modify `Sessions`, `Activity Responses`, and `Sensor Data` permissions is conditional on the `Participation` permission being set to _View_ or _Full_. ![Participation Dependence](/assets/roles-and-permissions-participation-dependence.png) - **Sessions and Activity Responses Correlation**: The permission level for `Activity Responses` is dependent on the `Sessions` permission level. If `Sessions` is set to _View_, then `Activity Responses` can be set to _None_ or _View_. Conversely, if `Sessions` is _Full_, `Activity Responses` can also be set to _Full_. ![Sessions and Activity Responses Correlatio](/assets/roles-and-permissions-sessions-and-activity-responses-correlation.png) ## Troubleshooting ### I can't see one or more pages/elements in the researcher dashboard This is likely due to permission restrictions. Contact your study's owner or permission managers to get the necessary permissions. Also, you can adjust your permissions if you are a permission manager. # Data Sources Data Collection in Avicenna can be divided into two broad categories: the first, called [_Activities_](../activities/), involves the data that participants provide by actively interacting with the Avicenna app, such as responding to a survey or completing a cognitive task. The second, called _Data Sources_, involves the data that is automatically collected without the participant being directly engaged in it, for example collecting GPS data and step count. Data sources can refer to different sensors, such as GPS, or be in the form of digital footprints, such as screen time, or be collected from wearables such as Google Fit devices. The common attribute between all of them is that participants don’t have to actively engage in collecting this data. They provide the necessary permissions initially when they join the study, and the rest happens automatically. In this section, we explain how you can view, add, or modify data sources in your Avicenna Study. We also explain what data sources are available and what kind of data each of them collects. ## Accessing Data Sources In order to access the list of data sources currently monitored as part of your study, go to the Researcher Dashboard and navigate to the `Data Sources` page: ![Accessing list of data sources for a given Avicenna study](/assets/data-sources-list.png) Here you can add or remove data sources from your study. To add a new data source, click on the `Add New Data Source` button. On the dialog that opens, you can see the list of all data sources Avicenna supports. Scroll through the list and click on the data source you are interested in. This will take you to another dialog to enter some details about this data source: ![Add a new data source](/assets/data-sources-add-new-data-source-dialog.png) In this dialog, first, you should specify whether providing this data source is mandatory or optional for your study participants. If a data source is marked as optional, the Avicenna app allows participants to opt out of this data source within the app. Note that in most cases, participants can simply revoke the necessary permissions for Avicenna to collect the requested data source. In this case, this lack of necessary permission is reported via the [Audit Trail](../study-setup-and-deployment/audit-trail.md). You also should choose a _Name_ and a _Description_ for your data source. These values will be shown to the participant to explain what is being collected and why. You may add more details on why your study collects certain data sources within the informed consent, but the description here can also help participants to better understand why a specific data source is needed for your study. After completing these fields, press `Add` to add your new data source and set up its data table. You will then be taken back to the study’s _Data Sources_, where you can see the list of data sources along with their configurations in your study. If you click on each data source's menu, you can see a few options: ![Menu options for a data source](/assets/data-sources-row-menu-options.png) In this menu, pressing `Go to Data Export` will take you to the _Data Export_ page where you can export the data collected by this data source. You can also press the `Remove` button and confirm your intent if you want to remove the data source from your study. This will stop collecting that data for your study immediately. If you want to delete the data for this data source as well, mark the _Delete the data from the data source_ checkbox as checked. If for any reason you decided to delete the data after you deleted the data source with that checkbox left unchecked, please contact [Avicenna support staff](mailto:support@avicennaresearch.com). :::note If any activity in your study contains at least one [Proximity triggering logic](../../reference/activities/triggering-logics.md#proximity-tl) in its latest version (whether published or draft), the Bluetooth Beacon data source cannot be removed. Similarly, activities containing at least one [Geofencing triggering logic](../../reference/activities/triggering-logics.md#geofencing-tl) will prevent removal of the GPS data source. ::: To edit a data source, simply press `Edit` and apply your modifications. ## Common Data Fields You can access the collected data either by exporting them via the _Data Export_ page, or by directly querying them using [Kibana](../../reference/analysis/kibana-basics/). The data format is different based on the data source, for example, GPS data contains location coordinates, while the Pedometer data contains the number of steps taken. Regardless, there are some common fields for each record of each data source that we explain below. **Study ID:** The unique ID of the study provided the data. Internally stored as `study_id`. **User ID:** The unique ID of the participant provided the data. Internally stored as `user_id`. **Device ID:** The unique ID of the smart device provided the data. Internally stored as `device_id`. **Record Time:** The time this record was captured. Internally stored as `record_time`. **Relative Record Time:** The time this record was captured, relative to the participation period's start time, in milliseconds. For example, 3,600,000 indicates the record was captured 1 hour after the participant joined the study. Internally stored as `rel_record_time`. Please note that this field won't be updated if you [change a participant's start time](../../reference/study-setup-and-deployment/participation.md#modify-participation-period). ## Data Collection Behavior of Avicenna Avicenna supports collecting data from Android, iOS, and wearable devices. Collecting data from some data sources needs specific permissions. If participants join a study that has any of those data sources and the corresponding permissions are not granted already, participants will see a message at the top of the study homepage stating that the study setup is incomplete. They should either grant necessary permissions or select `Don't have this device`. Choosing the latter option, which is available for wearable data sources only, excludes that data source for that particular participant. The participant can still grant permissions later by visiting the _Data Sources_ page of the study. The Avicenna app also lets the participants revoke such permissions. If the participant is participating in the study using only the web app, smartphone sensor data won't be collected, but wearable data still will be collected. That's because Avicenna collects wearable data from OEM's data servers (e.g. server of Garmin) instead of directly connecting to the physical device. Avicenna asks the participant's permission to have access to their account on the OEM's servers, and then it collects data from the servers at the end of every day. That's why you can configure such data sources using the web app too. For collecting data from sensors embedded in Android and iOS devices such as GPS or Pedometer, Avicenna requests data from the OS once every 5 minutes. iOS guarantees this 5-minute interval while Android doesn't guarantee it and might provide data either less often or more often than 5 minutes. The operating system of Android and iOS devices collects sensor data in two approaches: _Continuous_ (e.g. pedometer) or _Episodic_ (e.g. GPS). In the continuous approach, the device's operating system continuously collects data. The OS then provides all the collected data to the Avicenna app when Avicenna queries it from the device. For example, Android and iPhone devices continuously count the participant's steps. If a study has the _Pedometer_ sensor enabled, the Avicenna app queries the pedometer data once every 5 minutes, but it gets the total number of steps taken since the last request. So even though the Avicenna app queries data once every 5 minutes, it collects all steps taken by the participant. Similarly, Android and iPhone always check whether the screen is on or off. When the screen state changes, the OS notifies the Avicenna app, regardless of the 5-minute data query interval. In the episodic approach, Avicenna asks the OS every 5 minutes to collect data for a certain period, called _Burst Length_. The burst length is different for different data sources. For example, GPS keeps collecting data until it reads three accurate data points in a maximum time of 60 seconds. For battery, Avicenna collects one record in each cycle. For the accelerometer, Avicenna collects data for 60 seconds. For details on the data collection behavior of each data source, please refer to the relevant documentation page following this section. ## Troubleshooting ### Low or missing records If you think some data records are missing or there are fewer data records than you expected, whether after exporting/downloading the data or by viewing the `In-Operation` or other plots on the `Participation` page: 1. Check [the general steps to diagnose participation issues](../../reference/study-setup-and-deployment/participation.md#general-steps-to-diagnose-participation-issues). 2. Check if the study setup (that pink banner at the top of the study's homepage) is completed. You can check [the Application State logs on Kibana](../../reference/analysis/kibana-basics/README.md#application-state) to see which permissions are granted/revoked or not granted at all. Note that some data sources might not need specific permission. On the other hand, the participant should prevent the mobile app from being restricted/terminated by the operating system. Check these pages for more details: - [Background Data Collection](from-smartphone/background-data-collection/README.md) - [Android Battery Optimization Workarounds](from-smartphone/background-data-collection/android-battery-optimization-workarounds.md) - [Android Background Permission Workarounds](from-smartphone/background-data-collection/android-background-permission-workarounds.md) - [Don't Kill My App](https://dontkillmyapp.com/) 3. If you haven't marked your data source as `Mandatory`, the participant might have opted out of its data collection. You can check that by [the `Study Data Sources` field under Application State logs on Kibana](../../reference/analysis/kibana-basics/README.md#application-state). 4. Check [the data collection behavior of Avicenna](#data-collection-behavior-of-avicenna) to understand possible limitations and differences between Android and iOS, and see what you can expect in general. For each data source, check the additional details, if any, on the collection behavior under their own pages. For example, for GPS, see [this section](from-smartphone/location.mdx#data-collection-behavior). 5. Check if the participant is using the web app by [checking their devices](../../reference/study-setup-and-deployment/participation.md#participation-tab). Some data sources (e.g., GPS) collect data using mobile apps only. 6. Check for [the "Data Collection Failed"](../../reference/study-setup-and-deployment/audit-trail.md#130-data-collection-failed) and ["Data Collection Cycle Did Not Start"](../../reference/study-setup-and-deployment/audit-trail.md#108-data-collection-cycle-did-not-start) audit logs. 7. Check if the sensor is working properly on the device. You can test that by collecting similar data using other apps or, in the case of wearable data sources (e.g., Garmin), see if you or the participant can see any data under the corresponding accounts. --- sidebar_position: 1 --- # App Usage > Supported in Android. This data source records how often participants are using which app. The captured data only includes the name of the app and the aggregate amount of time it was used over a certain period. _It does not include any content of the application._ Each app usage record includes the following: **App Name:** The unique code name of the app used, for example, _com.ethica.logger_ for Avicenna or _com.facebook.kanata_ for Facebook. Internally stored as `app_name.` **Start Time:** The beginning of the time period over which this report was collected. Note that this does NOT refer to the time the application was started. Internally stored as `start_time.` **End Time:** The end of the time period over which this report was collected. Note that this does NOT refer to the time the application was closed. Internally stored as `end_time.` **Last Used:** Last time the application was used (the time the app was closed), in the time window specified by the `start_time` and the `end_time.` Internally stored as `last_used.` **Foreground Time (MS):** The amount of time, in milliseconds, that the application was in the foreground during the time window specified by the `start_time` and the `end_time`. An app is considered foreground if one of its screens is the currently active screen and the user is looking at it (i.e. the screen is on) or interacting with it. Internally stored as `foreground_time_ms`. As an example, if a record is shown as follow: ``` { "study_id": 1, "user_id": 1, "device_id": "b66448991d665fb3", "app_name": "com.google.android.youtube", "record_time": 1550942264787, "start_time": "May 9th 2018, 09:30:45.537+0000", "end_time": "May 10th 2018, 09:30:45.536+0000", "last_used": "May 10th 2018, 09:03:54.098+0000", "foreground_time_ms": 12379944 } ``` It means during the 24 hour period from May 9th 2018, 09:30:45.537+0000 to May 10th 2018, 09:30:45.536+0000, the participant was using YouTube (com.google.android.youtube) for approximately 206 minutes (12,379,944 milliseconds). ## Configuration in Android Monitoring app usage statistics has been integrated into the core functionalities of the Avicenna app. In studies where app usage data monitoring is required, Avicenna handles this internally without the need for any additional installations. Upon registration, participants will receive a notification through the Avicenna app to grant permission to access app usage data. This notification provides participants with an easy way to navigate to the required settings and grant permission. By eliminating the need for a separate extension app, we have streamlined the process, making it more straightforward for participants. Now, they need to download and install the Avicenna app from the Google Play Store, provide the necessary permissions, and they're all set. Alternatively, participants can be instructed to follow the steps below to grant permission via device settings, before they receive the notification from the Avicenna app: 1. Open Android's Settings. 2. Click on `Security`. 3. Scroll down to find and then select `Apps with access to usage data`. 4. From the list of applications shown, select `Avicenna`. 5. Switch `Allow usage tracking` to `On`. This will provide the required permission for Avicenna to access statistics on app usage. ## Android Apps with 0 ms Usage This data source captures any app that is running on the participant's Android device, even if they don't interact with that app directly. An example is _Google Mobile Services_ which usually runs behind the scenes and performs support tasks. But as it's running, the collected data will include references to it (`com.google.android.gms`), indicating that it's been used for 0 milliseconds. If you are focused on the apps the participant has directly interacted with them, you can exclude the results with 0 ms foreground time. --- sidebar_position: 2 --- import SampleDataButton from '@site/src/components/sample-data-button'; # Battery > Supported in Android & iOS. This data source monitors the battery status of the device. The battery data source has three unique features: - Unlike other data sources which can be unavailable on certain devices (e.g. smartphones without accelerometer), almost all devices are shipped with batteries. That guarantees that regardless of device type, this data will be available. - Unlike some data sources such as GPS where the user can turn off the sensor manually, the battery data source cannot be turned off. - Avicenna guarantees that in each operation cycle, it reads exactly one battery record. These features allow us to infer certain information from battery data. First and foremost, battery data provide information on the charging, discharging, and power consumption of the device. This allows us to measure how fast the battery drains, and how often the participant has to charge their device. Additionally, as Avicenna guarantees exactly one battery record per operation cycle, this data can clearly show for how long the app was operational and how long it was not, for reasons such as the device being turned off or the app being stopped explicitly. Furthermore, the battery data can be combined with data from other sources to assist behavioral analysis. For example, if the phone is plugged into the wall, we can be almost certain that the person was not carrying the device, and therefore any activity readings during that period should be treated with caution. Each battery record includes the following: **Level:** Current battery level, from 0 to _Scale_. Internally stored as `level`. **Scale:** Maximum battery level. Internally stored as `scale`. **Plugged:** Whether the device is plugged or not. It can contain one of the following values: - `0` indicating the device is on battery. - `1` indicating the current power source is AC. - `2` indicating the current power source is USB. - `3` indicating the current power source is wireless. Internally stored as `plugged`. **Status:** Status of the battery with respect to charging. It can be one of the following values: - `1` the battery status is unknown. - `2` the battery status is charging. - `3` the battery status is discharging. - `4` the battery status is not charging. - `5` the battery status is full. Internally stored as `status`. **Temperature:** Shows the current battery temperature in tenths of celsius. Android only. iOS records will always store 0. Internally stored as `temperature`. **Voltage:** The current battery voltage level in millivolt. Android only, iOS records will always store 0. Internally stored as `voltage`. --- sidebar_position: 3 --- # Contact Network ## Bluetooth > Supported on Android. Scans and monitors Bluetooth signals in the surrounding environment. Each Bluetooth record includes the following: **Device Name:** The friendly name of the Bluetooth device in proximity. Internally stored as `dev_name`. **Device Class:** The class of the Bluetooth device in proximity, in HEX value. This class determines the type of the device, such as a set-top box, or smartphone. Internally stored as `dev_class`. **MAC Address:** The MAC address of the device. Internally stored as `mac`. **RSSI:** Received signal strength, in dBm. Internally stored as `rssi`. ## Bluetooth Beacons > Supported on Android & iOS. Choosing this data source will instruct the Avicenna app on Android and iPhone devices to continuously scan for Bluetooth Beacon devices in proximity, and record the relevant beacons. ### Basic Concept Bluetooth Beacons are low-cost external wearable devices which can be carried by participants, attached to physical objects, or placed at specific locations such as rooms. They are powered by a button cell battery and can function from a few months to a few years, depending on their configuration, without any battery replacement. Beacons are not capable of storing large data or running applications. They only continuously announce their presence in the environment. When the participant's smartphone running the Avicenna app is in their proximity, the app hears the beacon and records its presence. This information later can be used to infer the proximity of the participant to another participant carrying a beacon, or to a specific object (like their car), or a specific room in a building. While there are many beacon manufacturers globally, the majority of them function based on one of the two popular standards: iBeacon developed by Apple and Eddystone developed by Google. Most beacons support both these standards and can be configured to work as either of them. For technical reasons, Avicenna only uses the iBeacon standard designed by Apple. Therefore, you should be able to use any beacon with iBeacon support. Avicenna has been successfully tested with beacons manufactured by [Kontakt.IO](https://kontakt.io/), [Accent Systems](https://accent-systems.com/), and [Gimbal, Ltd.](https://gimbal.com/), though you can choose any other manufacturer as long as their beacon comes with iBeacon support. Note that while Avicenna uses iBeacon, the Bluetooth Beacon data source is recognized and functions as expected both on Android and iPhone devices. If you want to use a beacon for your Avicenna study, you need to first configure it to operate as iBeacon. Usually, that means using the manufacturer's iPhone or Android app to connect to the beacon and set it to signal as an iBeacon device. At this step, the app will ask you to provide three pieces of information: - **Universally Unique Identifier or UUID**: An example is `4D0395FF-6470-44AC-9550-A27B3E6387FD`. - **Major Number:** A number from 0 to 65535. - **Minor Number:** A number from 0 to 65535. UUID is an ID unique to your study. You can find your study's UUID in the [Beacon Mapping tab](#beacon-mapping-page) of the _Data Sources_ page. Your beacon continuously announces this ID, so only participants in your study can find them. Major and Minor together distinguish this beacon from all other beacons you have defined and used in your study. Note that numbers can be specified in decimal or hexadecimal base. UUID is always written in hexadecimal and therefore has a combination of numbers and letters. Major and Minor numbers can be specified either in decimal or hexadecimal. Avicenna always shows the decimal value. When you want to enter these numbers in the beacon manufacturer's app to configure the beacon, make sure you enter the number in the correct base. Each beacon you use in your study requires a unique combination of Major/Minor number. To calculate these two numbers, you need to specify the following information for the given beacon in Avicenna: - **Team ID:** The ID of the team the beacon belongs to. You can think of teams as a few related participants, or the participant and their alters, or physical objects of interest related to the participant. A given study can have up to 4096 teams, each with a unique ID ranging from 0 to 4095. - **Role ID:** The ID of the role that the beacon belongs to. A given study can define up to 8 roles, each with a unique ID ranging from 0 to 7. Note that IDs for the similar roles should be unique across teams. For example, if you assign cars as role ID 0, you cannot change their role ID for other teams. - **Subject ID:** The ID of the beacon, which distinguishes the beacon from other beacons with the same team and role. A given beacon team/role combination can have up to 131072 beacons, with ID ranging from 0 to 131071. Given these numbers, Avicenna can provide you with a unique Major/Minor value and a UUID. You can use this information to configure the beacon as an iBeacon. Assigning Team, Role, and Subject ID to each of your study beacons depends on your study design. Avicenna provides some examples [here](#designing-beacon-based-studies) which can better clarify how you can specify these IDs. ### Data Fields Each Bluetooth beacon record includes the following data: **Device Class:** The class of the observed Bluetooth beacon, in HEX value. Android only, iOS records will always store 0. Internally stored as `dev_class`. **Device Name:** The name of the observed Bluetooth beacon, assigned to it while configuring the beacon. Android only, iOS records will always store `none`. Internally stored as `dev_name`. **MAC Address:** The MAC address of the observed Bluetooth beacon device. Android only, iOS records will always store `none`. Internally stored as `mac`. **Payload:** The concatenation of Major and Minor value of the observed Bluetooth beacon. Internally stored as `payload`. **Team ID:** The Team ID of the observed Bluetooth beacon. Internally stored as `team_id`. **Role ID:** The Role ID of the observed Bluetooth beacon. Internally stored as `role_id`. **Subject ID:** The Subject ID of the observed Bluetooth beacon. Internally stored as `subject_id`. **RSSI:** Received signal strength, in dBm. Internally stored as `rssi`. **Destination:** The label of the observed Bluetooth beacon, as defined in the `Beacon Mapping` tab of the _Data Sources_ page of the Researcher Dashboard (more [here](#beacon-mapping-page)). When Avicenna server receives a beacon record, prior to storing it in the database, it will check what is the label for the observed beacon, based on its unique set of Team ID/Role ID/Subject ID. This value then is stored together with the beacon record. Internally it's stored as `dst`. ### Designing Beacon-based Studies When you are designing a study to use Bluetooth Beacons, you should distinguish between two components: - Participants who install the Avicenna app on their Android or iPhone smartphone and their app is continuously looking for Bluetooth Beacons in proximity. - Bluetooth Beacons which are configured to announce their presence continuously for any participant in proximity to find them. It’s important to note that participants and beacons are separate entities, and while you can assign a beacon to each participant, you don’t have to do so. In general, studies using beacons can be grouped into three categories: The first group includes studies that are focused on capturing the interaction between participants. In such studies, each participant is expected to continuously search for other participants in the vicinity, so they need to have the Avicenna app installed on their smartphone. They are also required to broadcast their presence to other participants. Therefore, they need to carry a Bluetooth Beacon with them at all times. Therefore, the number of beacons in these studies is the same as the number of participants. The second group includes studies that capture the interaction of participants, and also the interaction between participants and non-participant items. For example, the amount of time participants spend together and the time they spend in different rooms in the building. In this case, similar to the first group, participants need to have the app installed as well as carrying a beacon. Additionally, there should be beacons configured and placed in each room. Therefore, the number of beacons in the study is more than the number of participants. The third group includes studies that capture the interaction between participants and non-participant items. For example, a study may want to measure the amount of time participants use their bike. In this case, participants need to have the Avicenna app installed to listen for the proximity to the beacons, but they don’t need to carry a beacon themselves. Each object (in this case, bikes) need to have a beacon attached to it. Therefore, the number of beacons and the number of participants are not related. There can be more or fewer beacons than the number of participants. Regardless of the study design, each beacon and participant part of the study should be assigned a _team ID_, a _role ID_, and a _subject ID_. These numbers are used by Avicenna app to know who is this beacon that is in proximity. The Avicenna app continuously looks for beacons around and records their Team/Role/Subject ID. Therefore, you need to make sure these IDs are unique for each subject (i.e. beacon and subject). If a given participant is expected to install the app and carry a beacon (as described in the first and second case above), you should assign the same Team/Role/Subject ID to both the participant and their beacon. This way, when the participant’s app scans the environment looking for beacons in proximity, it can recognize the participant’s own beacon and skip recording that as a separate subject. ### Beacon Mapping Page If your study includes Bluetooth Beacon data source, you can manage the beacons defined in Avicenna via the `Beacon Mapping` tab of the _Data Sources_ page of your Researcher Dashboard, as shown in the image below: ![Beacon Mapping tab of Data Sources page in Avicenna Researcher Dashboard](/assets/data-source-beacon-mapping.png) At the top of this page, you can find your study's UUID. For example, in our demo study the UUID is `4d0395ff-6470-44ac-9550-a27b3e6305a1`. This will be a different value for your study. To define a new beacon in Avicenna, click on the `Add` button on the top right corner of the page. This will open the `Add a New Beacon` dialog: ![Adding New Beacon to Your Study](/assets/data-source-beacon-mapping-add-new.png) In this dialog, you need to specify whether this beacon belongs to a participant or not. We [explained above](#designing-beacon-based-studies) that each beacon in your study can either belong to a participant or not, e.g. it can belong to their bike, or their car, or a particular room, or a non-participant individual. If you choose the `Participant Owned` option, then you need to specify which currently enrolled participant, or currently invited participant, owns this beacon. In contrast, choosing `Label` indicates that this beacon is not owned by a participant, and therefore you can assign a label to it. For example, `ROOM01`, `BIKE_12`, or similar. Then you need to assign a team ID, a role ID, and a subject ID to this beacon as well. After entering all the values, pressing `Add` will create the new beacon mapping in Avicenna. ![List of Beacon Mappings in Avicenna Study](/assets/data-source-beacon-mapping-list.png) The image above shows a study with 4 beacon mappings, where 1 of them is for our only participant, and the other 3 are for non-participant beacons. You can see each row contains all the information you need to configure your beacon: - Study UUID is written on the top of the page. This value is unique for the entire study. - Beacon name is written in the `Name` column, e.g. `ETH05a10054009a`. - iBeacon major and minor values are written in the `Major` and `Minor` columns, respectively. Note that these values are written in HEX. If your beacon manufacturer's app requires decimal values, convert them before using them to configure the beacon. ### An Example Study using Beacons In this section, we describe how you can set up a study which uses Bluetooth Beacons. Here, we assume your study is intended to track the interaction between family members. Your study is planning to recruit 10 subjects, from 3 families, with the following family structure: - **First family**: mother, father, son, and daughter. - **Second family**: mother, father, and daughter. - **Third family**: mother, father, and son. We consider each family as a team, and assign them a unique ID: - Team #1 -> First family - Team #2 -> Second family - Team #3 -> Third family Avicenna supports defining the maximum of 4095 teams within the same study. If your study does not require dividing participants into teams, you can simply assign all to team #0. Within each team (here, a family), we have the following roles, and we assign a unique ID to each role as well: - Mother -> Role #1 - Father -> Role #2 - Son -> Role #3 - Daughter -> Role #4 Note that not every team is required to have a member for each defined role. In this example, team #2 (second family) does not have any member for role #3 (son), and team #3 (third family) does not have any member for role #4 (daughter). Each role should be assigned a unique ID across all the teams. If two roles are mutually exclusive between two teams, they cannot have the same role ID. They still are required to have a unique ID. Avicenna supports defining up to 8 roles within each study, marked with ID 0 to ID 7. Similar to team definition, if your study does not require assigning roles to the participant, you can simply assign role #0 to all participants. Within each role of each team, there can be 0 or more subjects. Each subject also should have a unique ID, called Subject ID. Note that you can use the same subject ID across roles or teams. For example, the mother of team #1 can have subject ID of 1, the father of team #1 also can have subject ID of #1, and both daughter and son of team #1 also can have subject ID of #1. You might still choose to assign a unique ID to each subject across your study, or at least within each team for more clarity, but that is not necessary. Avicenna supports defining the maximum of 131,072 subjects within each role of each team, marked with ID 0 to ID 131071. **Participant Enrollment** When you choose to use Bluetooth Beacons to capture interactions between your study participants, you need to assign a team ID, a role ID, and a subject ID to each individual joining your study. _These values should be set before the participant joins your study._ You can either invite the participant first, and then set these values for them in the [Beacon Mapping page](#beacon-mapping-page) (before they use the invitation to join the study), or you can set them directly during the invitation, as explained below. In our example above, assume the contact information for each family member is as follow: | | First Name | Last Name | Email | Team # | Role # | Subject # | | -------- | ---------: | --------: | ---------------: | -----: | -----: | --------: | | Mother | Mom | Family1 | mom@family1.com | 1 | 1 | 1 | | Father | Dad | Family1 | dad@family1.com | 1 | 2 | 2 | | Son | Boy | Family1 | boy@family1.com | 1 | 3 | 3 | | Daughter | Girl | Family1 | girl@family1.com | 1 | 4 | 4 | To invite members of this team to join your study, navigate to `Participation -> Invitation` page of your study. Then click on the `Invite Participants` to start creating your invitations. Note that your study's _Enrollment Type_ does not have to be _By Invitation Only_ in order for you to invite participants. If you have set your study to _By Invitation Only_, no one else other than invited individuals can join. If you have set your study to _be Public_, anyone can join the study, whether invited or not. In the _Invitation List_ dialog, you can enter the list of individuals you want to invite, one invitation per line. You can type the maximum of 100 invitations each time (maximum of 100 lines in the dialog). Each line must include the invitee's email address. You might choose to enter their first name and last name as well, though that is not mandatory. Additionally, you also have to specify the individual's team/role/subject ID. While this is specified as optional, we do have to include it here. The following lines show the invitations for the above list of participants from team #1: ``` mom@family1.com,Mom,Family1,{"team": 1, "role": 1, "subject": 1} dad@family1.com,Dad,Family1,{"team": 1, "role": 2, "subject": 2} boy@family1.com,Boy,Family1,{"team": 1, "role": 3, "subject": 3} girl@family1.com,Daughter,Family1,{"team": 1, "role": 4, "subject": 4} ``` As mentioned above, including first name and last name is not mandatory and you can leave them empty if you choose to. In that case, the invitations would be as follow: ``` mom@family1.com,,,{"team": 1, "role": 1, "subject": 1} dad@family1.com,,,{"team": 1, "role": 2, "subject": 2} boy@family1.com,,,{"team": 1, "role": 3, "subject": 3} girl@family1.com,,,{"team": 1, "role": 4, "subject": 4} ``` Note the additional commas between the email address and the ID list for each invitation. Make sure you properly add the commas to indicate that each row includes the email address, skips the first and the last name, and finally includes the required IDs. Pressing the `Invite` button will add these email addresses to the study's invitation list. Please make sure you enter the email address for invited participants correctly. Also, participants have to use the email addresses entered here in order to join the study (as opposed to using an alternative or alias address). Avicenna uses the email addresses to identify the participant, check whether they should be allowed to join the study or not, and what team/role/subject they should be assigned to. When done, you can ask participants to download the Avicenna app on their iPhone or Android smartphone and join the study. If they already have an account with Avicenna and have the app installed, they only have to click on the study's registration URL on their phone in order to join the study. Avicenna app will validate their invitation, enrolls them in the study, and allocates them the correct ID (as specified here). If they do not have an account, when they click on the study registration URL, they will be asked to download the Avicenna app on their phone and create an account. They need to use the email address you have entered while inviting them during the signup. When a given invited participant has joined the study, their record will be removed from the _Invitation_ list and will be added to the _Adherence_ list. You can follow up on their study progress through the _Adherence_ section. Note that for privacy reasons, the _Adherence_ page does not show the participant's name or email address, and only refers to them using their _Avicenna ID_ (which is different from team ID, role ID, and subject ID specified above). The _Avicenna ID_ will be shown along with their name and email address while they have a pending invitation in the _Invitation_ list. You can use that information prior to their enrollment to manually map _Avicenna ID_ to the email addresses. **Preparing the Beacons** Bluetooth Beacons allow you to capture minute-resolution contact pattern between the participant and any other item of interest, whether other study participants or specific objects or locations. For this purpose, any item you want to be monitored should always be accompanied by a Bluetooth Beacon. For example, if you want to capture the interaction between two participants, both of them should carry a Beacon at all times. Alternatively, if you want to capture the number of times the participant visits a certain room in a building, the participant should carry a Beacon all the time, and another Beacon should be installed in the room. Similarly, if you want to capture the interaction between the participant and their pet, the participant should carry the Beacon and another Beacon should be attached to the pet. Each Beacon, regardless of where it's mounted or who is carrying it, should be configured with its team ID, role ID, and subject ID. Otherwise, Avicenna app will not capture their proximity and your study will not record any information about the presence of the Beacon. In our example above, each family member should carry their own Beacon, and their Beacon should be configured with participant's unique team/role/subject IDs as described here, prior to being handed out to the participant. It's important to note that Avicenna captures participants in proximity only using their Beacon. So participants should not exchange their Beacon under any circumstances unless the Beacon is re-configured with their ID. Otherwise, Avicenna assumes the presence of the original owner of the beacon, which can lead to incorrect data. **Configuring Beacons** You need to configure each Beacon with the following information: - Name - UUID - Major - Minor You can find all these fields in the `Beacon Mapping` tab of the _Data Sources_ page of the _Researcher Dashboard_, as [shown above](#beacon-mapping-page). Beacons, regardless of their manufacturer, provide support for two common standards: _Eddystone_ by Google and _iBeacon_ by Apple. Almost all Beacons are capable of working as either Eddystone or iBeacon. Avicenna uses iBeacon standard, so while purchasing Beacons, you need to make sure it does support iBeacon. For each Beacon, we need to perform the following tasks: **1. Turn off all profiles except one iBeacon:** Most Beacons are capable of working as iBeacon and Eddystone, even at the same time. Each of these is referred to as a _Profile_. The Beacon can be configured to specify what information it should continuously broadcast from each active profile. As mentioned before, Avicenna only works with iBeacon. Therefore, to preserve the battery, you need to turn off all the available profiles, except one iBeacon. **2. Configure the iBeacon profile:** As the second step, you need to configure the iBeacon using the Name, UUID, Major, and the Minor value assigned to the given participant. This can be done either through the manufacturer's app, the manufacturer's web-based dashboard, or a combination or both. The details of how to perform these tasks on each beacon are different for different manufacturers. In this example, we will use [Kontakt.IO](https://kontakt.io/)[Beacon Pro](https://kontakt.io/blog/beacon-pro-for-proximity-solutions/). Depending on your needs, you can choose any other Beacon from this company, or any other manufacturer as long as they support iBeacon. When you purchase a set of Beacons from Kontakt.IO, you will receive an order ID. Start by creating an account on [Kontakt.IO's Web Panel.](https://panel.kontakt.io/signin) Then, use your order ID to add the Beacons you have purchased to your Web Panel account. This will add all the Beacons you have purchased to the Web Panel. Each Kontakt.IO Beacon can be identified using a 4-character ID printed on it when you purchase it. There will be one entry per Beacon on the Web Panel, where each entry has the same ID as shown on the Beacon. The following image shows 3 entries on our Web Panel account, for the three Beacon Pros we have purchased. ![Kontakt.IO Beacon Pro Registration](/assets/data-source-beacon-kontakt-io.png) Click on the first beacon to open the _General_ tab of the beacon. Here, under the _Device Profile_ section, you will see one iBeacon and multiple Eddystone options. Turn off all options except the iBeacon. Also, enter the UUID, Major, and Minor value for the first participant in the related boxes, as shown in the image below. When done, press Save Changes to store the configuration changes. Then, follow these steps for each other beacon as well. ![Configuration for One iBeacon in Kontakt.IO](/assets/data-source-beacon-kontakt-io-setting.png) _Depending on the software you use, you might have to enter the Major and Minor value in decimal or hexadecimal format. Please make sure you enter the correct format, otherwise, the system will not function correctly._ So far, we have specified the UUID, Major, and Minor of each beacon, but we have not configured the beacon device yet. Configuring a beacon has to be done using [Kontakt.IO's Administration App](https://goto.kontakt.io/). Moreover, Kontakt.IO does not allow setting the beacon's _Name_ through the Web Panel. Only the app can set the beacon name. In the next step, we will use the Administration App to transfer the UUID/Major/Minor configuration to the Beacon, and also set the Beacon's Name. After downloading and installing the Administration App on your Android phone, you need to log in to the app using the same credentials you used for Web Portal. This will show you the list of beacons you own, as shown in the following image. You can click on each beacon's ID individually and apply the configuration. ![Using Kontakt.IO App to Configure a Beacon](/assets/data-source-beacon-kontakt-io-app.png) Alternatively, you can choose the Bulk Configuration option to configure all beacons at the same time. Note that the beacons should be in proximity of the phone for the configurations to be transferred correctly. If any beacon failed to be configured, try the operation again to ensure the settings are configured on the beacon properly. ![Kontakt.IO App Showing Configuration Results](/assets/data-source-beacon-kontakt-io-showing-results.png) After applying the UUID, Major, and Minor to the beacon, you also have to set the _Name_ of the beacon. For this purpose, click on the beacon ID from the list, and choose _BLE Name_ from the options. In the opened dialog, enter the _Name_ as shown on Avicenna's Beacon Mapping page. ![Entering Beacon Name in Kontakt.IO App](/assets/data-source-beacon-kontakt-io-entering-name.png) When done, make sure you apply the changes to the beacon again. In the end, your beacon list should show all the values are entered correctly: ![Kontakt.IO App Showing Final Result](/assets/data-source-beacon-kontakt-io-final-result.png) When you are done with configuring a beacon, you can give them to the intended participant and ask them to carry it with them at all times during their participation. This way, Avicenna app will capture the presence of any study beacon in the proximity of this participant (hence, the presence of any other participant, object, or room), and also the presence of this participant will be captured by any other phone running Avicenna app (assuming the person is also part of the study). **Defining Surveys** In addition to capturing the contact between subjects in your study, you can configure Avicenna to trigger surveys when a certain type of contact is detected. To achieve this, you should add a Proximity-Triggered triggering logic to your survey, and set the remaining parameters accordingly. You can read more about this [here](../../activities/). --- sidebar_position: 4 --- # Environmental Sensors ## Ambient Temperature > Supported in Android. Measures the ambient room temperature in degrees Celsius. **Temperature:** Ambient air temperature. Internally stored as `temp_c`. **Accuracy:** Same as Accuracy in [Accelerometer](motion-sensors.mdx#accelerometer). ## Light > Supported in Android. Measures the ambient light level (illumination) in lx. Each light record includes the following: **Illuminance:** Illuminance, in lx. Internally stored as `illuminance_lx`. **Accuracy:** Same as Accuracy in [Accelerometer](motion-sensors.mdx#accelerometer). ## Pressure > Supported on Android & iOS. Measures the ambient air pressure in hPa or mbar. Usually used for monitoring air pressure changes. Each pressure record includes the following: **Pressure:** Ambient air pressure, in hPa or mbar. Internally stored as `pressure_hpa`. **Accuracy:** Same as Accuracy in [Accelerometer](motion-sensors.mdx#accelerometer). ## Proximity > Supported on Android. Measures the proximity of an object in cm relative to the view screen of a device. Typically is used to determine whether a handset is being held up to a person's ear. Each proximity record includes the following: **Distance:** Distance from an object, in centimeters. Internally stored as `dist_cm`. **Accuracy:** Same as Accuracy in [Accelerometer](motion-sensors.mdx#accelerometer). ## Relative Humidity > Supported on Android. Measures the relative ambient humidity in percent (%). Each relative humidity record includes the following: **Humidity:** Ambient relative humidity, in percent. Internally stored as `humidity_percent`. **Accuracy:** Same as Accuracy in [Accelerometer](motion-sensors.mdx#accelerometer). --- sidebar_position: 5 --- import SampleDataButton from '@site/src/components/sample-data-button'; # Location ## GPS > Supported in Android & iOS. This data source measures the precise location of the device using GPS sources. Each GPS record includes the following: **Satellite Time:** The time at which this GPS record was received. Internally stored as `satellite_time`. **Provider:** Determines how this GPS record was acquired. It can contain one of the following five options: - _GPS_: means the Avicenna app explicitly requested the user's location and received it from GPS satellites. - _Network_: means the Avicenna app explicitly requested the user's location and received it from nearby cell towers and Wi-Fi access points (only in Android) ([technical details](https://developer.android.com/reference/android/location/LocationManager#NETWORK_PROVIDER)). - _Fused_: means the Avicenna app is using a location API of Google Play service named fused location provider API. This API intelligently combines different signals to provide location information. - _GPS-Passive_: means other apps running on the participant's device requested location from GPS satellite, and Avicenna received a copy as well (only in Android). - _Network-Passive_: means other apps running on the participant's device requested location from nearby cell towers and Wi-Fi access points, and Avicenna received a copy as well (only in Android). - _Fused-Passive_: means other apps running on the participant's device requested location from fused location provider API, and Avicenna received a copy as well. - _GPS-Reuse_: means the app detected the participant did not move since the last GPS reading, and therefore the GPS records for the previous cycle are reused. - _Network-Reuse_: means the app detected the participant did not move since the last reading, and therefore the records of the previous cycle provided by the network provider are reused. - _Fused-Reuse_: means the app detected the participant did not move since the last reading, and therefore the records of the previous cycle provided by the fused provider are reused. This is internally stored as a `provider`. **Latitude:** The latitude of this record, in degrees. Internally stored as `lat`. **Longitude:** The longitude of this record, in degrees. Internally stored as `lon`. **Altitude:** The altitude of this record, in meters above the WGS 84 reference ellipsoid. Internally stored as `alt`. **Speed:** The speed of this record, in meters/second over the ground. Internally stored as `speed`. **Bearing:** The bearing of this record, in degrees. Internally stored as `bearing`. **Accuracy:** The accuracy of this reading, in meters. Internally stored as `accu`. ### Required Permissions When participants join a study that requires GPS, the Avicenna app will request permission to access their location data. Participants will have three options: - Decline the permission request. - Grant the permission, but only while the app is open and in use. - Grant permission once. If the Participant declines this permission, or grants it only while the app is in use, Avicenna will not collect any GPS data and will show the participant a notification to inform them that the missing GPS permission is interrupting their study participation. If the participant chooses "grant permission once," Avicenna is allowed to collect GPS data for a limited time, likely for one or two days. This period is determined by Android or iPhone operating systems. After this period, the permission is automatically revoked by the operating system, and Avicenna will ask the participant for permission again. The second time Avicenna asks the participant for the GPS permission, in addition to the 3 options listed above, the participant will have the fourth option, "Allow Always". Choosing this option grants Avicenna permanent permission to access GPS data, until it's revoked by the participant explicitly. The data collection continues as long as the participant is actively participating in the Study. Participants can revoke GPS permission at any time, turn off their device’s GPS (accessible from the home screen of most smartphones), or simply terminate the Avicenna app. In all of these cases, Avicenna will not collect any GPS data, and will notify them via a notification that their study participation has been interrupted. In this case, the missing data will be visible to the researchers on the [Participation Page](../../study-setup-and-deployment/participation.md#in-operation-event-plots) of the Researcher Dashboard. At any time, Participants can turn on their GPS, grant the missing permissions, or restart the app. Each of these events will resume the data collection in Avicenna immediately, and will remove the related notifications from the app. ### Data Collection Behavior Compared to other data sources, monitoring GPS requires considerable power and can drain a participant's battery rapidly. To reduce this impact, GPS data sources in Avicenna use different methods to collect as much data as possible and at the same time keep resource consumption very low. Understanding these helps you better understand and analyze the collected GPS data. **Collecting GPS Records** Avicenna starts collecting fresh GPS records every 5 minutes. Avicenna collects GPS data until it reads 3 accurate data points for a maximum period of 60 seconds. **Reusing GPS Records When Detecting Stationary State** Collecting fresh GPS data is very resource consuming. That's why at the beginning of each cycle, before Avicenna starts the GPS data collection, it checks if it can confidently conclude the participant has been stationary since the last GPS reading. If yes, the app simply reuses the GPS records from the last cycle. To detect whether the participant is stationary, Avicenna uses [motion-based activity recognition](motion-sensors.mdx#motion-based-activity-recognition) (MBAR) and [Wi-Fi](#wi-fi) data. In both Android and iOS, Avicenna considers the participant as stationary if all of the following conditions are met since the last cycle: - The app has been able to collect MBAR data with a high confidence value ([CMMotionActivityConfidence.high](https://developer.apple.com/documentation/coremotion/cmmotionactivityconfidence/high) in iOS and [100% Confidence](https://developers.google.com/android/reference/com/google/android/gms/location/DetectedActivity#public-int-getconfidence) in android). - All MBAR data collected indicate the phone has been stationary ([CMMotionActivity.stationary](https://developer.apple.com/documentation/coremotion/cmmotionactivity/1615430-stationary) in iOS and [STILL](https://developers.google.com/android/reference/com/google/android/gms/location/DetectedActivity#STILL) or [TILTING](https://developers.google.com/android/reference/com/google/android/gms/location/DetectedActivity#TILTING) in Android). If both of the above are `True`, the app assumes the device has been stationary during the last cycle. In addition to MBAR data, Avicenna on Android uses Wi-Fi data as well. Based on Wi-Fi data, Avicenna considers a device stationary if all the following conditions are true: - At least 3 Wi-Fi networks were detected in proximity (based on BSSID) in the previous cycle. - At least 3 Wi-Fi networks are detected in proximity (based on BSSID) in the current cycle. - The Wi-Fi network sets for the current cycle and the previous cycle have at least 30% similarity. If all of the above 3 conditions are met, Avicenna for Android concludes that Wi-Fi data suggest the participant has been stationary. Now, in each cycle, the Avicenna app skips collecting new GPS data and reuses data from the previous cycle, if the following conditions are met: - There is enough GPS data collected in the previous cycle; and - MBAR data exists and shows the participant has been stationary; or - (Android only) Wi-Fi data exists and shows the participant has been stationary. In this case, Avicenna finds the best GPS reading from the previous cycle, makes a copy of it, updates the `provider` value of the copied record by appending a `-reuse` to it, updates the `record_time` of the record to the current time, and uploads it as the GPS reading for this cycle. Note that in this case: - The `satellite_time` still refers to the time the data was collected originally, but the `record_time` refers to the time the stationary state was detected by the app, and the previous records were reused. - Only one record is uploaded, which is the most accurate reading from the cycle where fresh GPS data was collected. For example, consider the following GPS record: ```json { "study_id": 805, "user_id": 26988, "device_id": "a28bfb9b278sa99f", "record_time": 1603882030265, "rel_record_time": 14412439335, "provider": "gps-reuse", "satellite_time": 1603842281000, "location": { "lat": 32.693238, "lon": -97.175872 }, "speed": 0, "accu": 3.7900924682617188, "alt": 175.14569091796875, "bearing": 0 } ``` It shows a GPS record was collected at `1603842281000` (i.e. `Tuesday, October 27, 2020 23:44:41`, identified by `satellite_time`), had the accuracy of 3.7 meters, and was reused at `1603882030265` (i.e. `Wednesday, October 28, 2020 10:47:10.265`, identified by `record_time`). In this example, the GPS record was collected nearly 11 hours before it was reused. During these 11 hours, the Avicenna app had sent the same "reused" GPS record once for each cycle. Also, it worth mentioning that the above GPS data reuse only works if the study has MBAR and/or Wi-Fi data source added to the study, and the participant has been granted the necessary permissions. Otherwise, no data for MBAR or Wi-Fi will be available to Avicenna's GPS component, and the app will record fresh GPS data each cycle. **Passive Data Collection in Android** Android allows apps to listen for GPS records passively. It means an app like Avicenna does not have to actively ask for fresh GPS records. Instead, it can sign up to receive a copy of the GPS record that is requested by other apps (given that Avicenna holds required permissions to collect GPS data). This way, Avicenna can collect GPS data without causing additional battery consumption. Note that this behavior does not interfere with Avicenna's periodic GPS data collection. Avicenna collects GPS data periodically. The `provider`, in this case, is set to `gps`, `network`, `fused`, `gps-reuse`, `network-reuse`, or `fused-reuse`. It also listens to and records GPS records requested and received by other apps. The `provider`, in this case, is set to `gps-passive`, `network-passive` or `fused-passive`. For example, assume the participant is navigating from `Point A` to `Point B` using Google Maps, and the navigation takes 1 hour. During this 1 hour, Avicenna receives every GPS record requested by Google Maps, and records them as passive data. It also collects GPS data (fresh data, as the person is moving and is hot stationary), and stores the alongside the passive data. It is worth mentioning that while GPS records collected by Avicenna are still collected in 5-minute intervals, you might find passive GPS records captured between intervals as well. ### Mobility Mode Avicenna trained a machine-learning model named "GPS mobility mode classification" to detect the mobility mode of GPS data points. The algorithm preprocesses the GPS data to clean the data, remove noises, and extract kinematic features from the GPS data source. Then, it predicts the mobility mode of GPS data points using the extracted features. Here we first define terminologies and then explain the steps of the algorithm in detail. **GPS Trajectory**: A sequence of time-stamped GPS points for one user. **GPS Segment**: A GPS segment is a subdivision of a user’s trajectory, which is traveled by only one mobility mode (e.g., stationary, walking, driving). The steps of the algorithm are as follows: **1. Cleaning and Feature Extraction** - Remove data points that their latitude or longitude is not in the acceptable range. - Remove duplicated data points. - Downsample data to 5s frequency so that where we have more than one data point in a 5s interval, we only keep one point and remove the remaining points in that interval. - Calculate kinematic features (i.e., distance, speed, acceleration, jerk, bearing, and bearing rate). **2. Segmentation** - Segment each GPS trajectory into GPS segments using a trained machine-learning model. - Split GPS segments into smaller ones at points where the travel time between two consecutive GPS points exceeds 20 minutes. - Split GPS segments into smaller ones at points where the number of GPS data points exceeds a predefined value (i.e., 50). - Finally, small GPS segments with less than 5 data points are skipped with `mobiliy_mode = N/A`. **3. Mobility Mode Classification** - In the end, Avicenna utilizes its trained machine-learning model to predict the mobility mode of each GPS segment and appends the new data fields to the raw GPS data source. The model classifies each GPS segment to one of stationary, walking, and driving modes (internally stored as `stationary`, `walk`, and `car`). The machine-learning algorithm adds the following data fields to the GPS data source: **Distance-Feature Extraction**: The distance of this record from the previous record, calculated by our feature extraction algorithm. Internally stored as `distance_fe`. **Speed-Feature Extraction**: The speed of this record, in m/s, calculated by our feature extraction algorithm. Internally stored as `speed_fe`. **Acceleration-Feature Extraction**: The acceleration of this record, in m/s2, calculated by our feature extraction algorithm . Internally stored as `acceleration_fe`. **Jerk-Feature Extraction**: The jerk of this record, in m/s3. Jerk is the rate at which an object's acceleration changes with respect to time, calculated by our feature extraction algorithm. Internally stored as `jerk_fe`. **Bearing-Feature Extraction**: The bearing of this record, in degrees, calculated by our feature extraction algorithm. Internally stored as `bearing_fe`. **Bearing rate-Feature Extraction**: The bearing rate of this record which is the rate of bearing changes with respect to time, calculated by our feature extraction algorithm. Internally stored as `bearing_rate_fe`. **Segment ID**: Unique identifier of a GPS segment in a GPS trajectory. Internally stored as `segment_id`. GPS trajectories with fewer than 5 data points are excluded from segmentation and mobility mode classification steps, and their `segment_id` field is labeled as `N/A`. Note that the segment id is unique among data points of a GPS trajectory with unique (`study_id`, `user_id`, `device_id`) during a given month. **Mobility mode**: The mobility mode of this record (e.g. `stationary`, `walk`, `car`) predicted by our machine-learning model. Internally stored as `mobility_mode`. GPS segments with fewer than 5 data points are skipped in our mobility mode classification and their `mobility_mode` field is labeled as `N/A`. ## Wi-Fi > Supported in Android. Monitors Wi-Fi signals in the surrounding environment. This data source scans different frequency channels and records the Wi-Fi networks available. Each Wi-Fi record includes the following: **SSID:** Service Set Identifier, or the name of the network. Internally stored as `ssid`. **BSSID:** Basic Service Set Identifier, or the address of the access point in proximity. Internally stored as `bssid`. **Capabilities:** Describes the authentication, key management, and encryption schemes supported by the access point. Internally stored as `capabilities`. **Frequency:** The frequency (in MHz) of the channel over which the client is communicating with the access point. Internally stored as `freq`. **Level:** The detected signal level in dBm, is also known as the RSSI. Internally stored as `level`. ### Data Collection Behavior Android devices collect WiFi data in the following steps: - Android asks the OS to scan and send a list of all SSIDs in proximity. - OS sends the list, usually immediately. - Avicenna puts each SSID in one record. After getting the first batch of SSIDs, Avicenna continues scanning for 1 minute, and the OS keeps sending new data points. During data collection, the number of collected data records correlates to the proximity of the network. If a network is nearby, Avicenna will get a lot of records for its SSID (often with slightly varying levels of RSSI). But if a network is far, Avicenna collects fewer records, because OS will see this network less often in its scans. Note that Avicenna collects data points with different RSSI levels, frequencies, and BSSIDs for the same SSID and the same record time. --- sidebar_position: 6 --- import SampleDataButton from '@site/src/components/sample-data-button'; # Motion Sensors ## Accelerometer > Supported on Android & iOS. Measures the acceleration force applied to a device, including the force of gravity (Unit: m/s2). Data from the accelerometer, together with [Gravity](#gravity), [Gyroscope](#gyroscope), and [Magnetic Field](#magnetic-field) can provide a good estimate of the device's movement, and subsequently estimate the participant's physical activity. Each accelerometer record includes the following: **X-Axis:** Acceleration force along the x-axis (including gravity), in m/s2. Internally stored as `x_axis`. **Y-Axis:** Acceleration force along the y-axis (including gravity), in m/s2. Internally stored as `y_axis`. **Z-Axis:** Acceleration force along the z-axis (including gravity), in m/s2. Internally stored as `z_axis`. **Accuracy:** The accuracy of the reading. It can be either 1 for low accuracy, 2 for medium accuracy, or 3 for high accuracy. Internally stored as `accu`. ## Magnetic Field > Supported on Android & iOS. Measures the ambient geomagnetic field in μT. Each magnetic field record includes the following: **X-Axis:** Geomagnetic field strength along the x-axis, in μT. Internally stored as `x_axis`. **Y-Axis:** Geomagnetic field strength along the y-axis, in μT. Internally stored as `y_axis`. **Z-Axis:** Geomagnetic field strength along the z-axis, in μT. Internally stored as `z_axis`. **Accuracy:** Same as Accuracy in [Accelerometer](#accelerometer). ## Gyroscope > Supported on Android & iOS. Measures a device's rate of rotation in radians. Usually used for rotation detection (spin, turn, etc.). Each gyroscope record includes the following: **X-Axis:** The rate of rotation around the x-axis, in rad/s. Internally stored as `x_axis`. **Y-Axis:** The rate of rotation around the y-axis, in rad/s. Internally stored as `y_axis`. **Z-Axis:** The rate of rotation around the z-axis, in rad/s. Internally stored as `z_axis`. **Accuracy:** Same as Accuracy in [Accelerometer](#accelerometer). ## Linear Acceleration > Supported on Android & iOS. Measures the acceleration force in m/s2 that is applied to a device, excluding the force of gravity. This data source is usually implemented as a software-based data source and does not have a dedicated hardware chip on the smartphone. The device measures acceleration from the [Accelerometer](#accelerometer) sensor, and excludes the gravity measured by the [Gravity](#gravity) sensor, in order to calculate the linear acceleration. Each linear acceleration record includes the following: **X-Axis:** Acceleration force along the x-axis (excluding gravity), in m/s2. Internally stored as `x_axis`. **Y-Axis:** Acceleration force along the y-axis (excluding gravity), in m/s2. Internally stored as `y_axis`. **Z-Axis:** Acceleration force along the z-axis (excluding gravity), in m/s2. Internally stored as `z_axis`. **Accuracy:** Same as Accuracy in [Accelerometer](#accelerometer). ## Gravity > Supported on Android & iOS. Measures the force of gravity in m/s2 that is applied to a device. Usually used for motion detection (shake, tilt, etc.). Each gravity record includes the following: **X-Axis:** Force of gravity along the x-axis, in m/s2. Internally stored as `x_axis`. **Y-Axis:** Force of gravity along the y-axis, in m/s2. Internally stored as `y_axis`. **Z-Axis:** Force of gravity along the z-axis, in m/s2. Internally stored as `z_axis`. **Accuracy:** Same as Accuracy in [Accelerometer](#accelerometer). ## Orientation > Supported on Android & iOS. Measures the orientation of a device by providing the three elements of the device's rotation vector. Each orientation record includes the following: **X-Axis:** Rotation vector component along the x-axis (x \* sin(θ/2)). Internally stored as `x_axis`. **Y-Axis:** Rotation vector component along the y-axis (y \* sin(θ/2)). Internally stored as `y_axis`. **Z-Axis:** Rotation vector component along the z-axis (z \* sin(θ/2)). Internally stored as `z_axis`. **Vector Size:** Scalar component of the rotation vector (cos(θ/2)). This value might not be provided. Internally stored as `vector_size`. **Accuracy:** Same as Accuracy in [Accelerometer](#accelerometer). ## Pedometer > Supported on Android & iOS. Counts the number of steps taken by the participant over a certain duration. Avicenna uses Android and iOS standard algorithms to collect the count of steps taken. Please refer to [Google](https://developer.android.com/reference/android/hardware/Sensor.html#TYPE_STEP_COUNTER) and [Apple](https://developer.apple.com/documentation/coremotion/cmpedometerdata) documentation for implementation details in Android and iPhone devices. Each pedometer record includes the following: **Duration** The duration over which this record has collected data, in seconds. Internally stored as `duration`. **Steps** The number of steps taken by the participant over the specified duration. Internally stored as `steps`. **Accuracy** The accuracy of the record. Android only, iOS records will always store -1. Internally stored as `accu`. **Average Active Pace** The average pace of the participant, measured in seconds per meter. iOS only, Android records will always store -1. Internally stored as `avg_active_pace`. **Current Cadence** The rate at which steps are taken, measured in steps per second. iOS only, Android records will always store -1. Internally stored as `cur_cadence`. **Current Pace** The current pace of the participant, measured in seconds per meter. iOS only, Android records will always store -1. Internally stored as `cur_pace`. **Distance** The estimated distance (in meters) traveled by the participant. iOS only, Android records will always store -1. Internally stored as `distance`. **Floor Ascended** The approximate number of floors ascended by walking. iOS only, Android records will always store -1. Internally stored as `floor_ascended`. **Floor Descended** The approximate number of floors descended by walking. iOS only, Android records will always store -1. Internally stored as `floor_descended`. ### Data Collection Behavior Android and iOS devices behave differently in collecting pedometer data. In Android, the operating system sends data to the Avicenna app as soon as a step count is available. On iOS, Avicenna wakes up every five minutes—unless it is terminated—to query all steps taken during the past five minutes. In the event of app termination, Avicenna will collect data from the most recent time it fetched such data. The only limitation is that the iOS provides data for the past seven days. ## Motion-Based Activity Recognition > Supported on Android & iOS. Uses a combination of motion sensors to detect the type of activity that the participant is currently engaged in. Avicenna uses Android and iOS standard algorithms to detect the participant's type of current activity. Please refer to [Google](https://developers.google.com/android/reference/com/google/android/gms/location/ActivityRecognitionResult) and [Apple](https://developer.apple.com/documentation/coremotion/cmmotionactivity) documentation for implementation details in Android and iOS devices. Each activity recognition record includes the following: **Activity Type:** The type of recognized activity. Internally stored as `activity_type`. It can be one of the following values: - `0`: Unknown. Unable to detect the current activity. - `1`: Still. The device is still (not moving). - `2`: Tilting. The device angle relative to gravity changed significantly. This often occurs when a device is picked up from a desk or a user who is sitting stands up. - `3`: On-Foot. The device is on a participant who is walking or running. - `4`: Walking. The device is on a user who is walking. This is a sub-activity of On-Foot. - `5`: Running. The device is on a user who is running. This is a sub-activity of On-Foot. - `6`: On-Bicycle. The device is on a bicycle. - `7`: In-Vehicle. The device is in a vehicle, such as a car. Please note that we can have different activity types at the same time. For example, if the participant is driving and stops in some places during driving, we will have two records at the same time with different activity types: `In-Vehicle` and `Still` **Confidence Level** A value that represents the algorithm's confidence in the recognized activity. Internally stored as `confidence_level`. For Android devices, the confidence level is a value between 0 to 100, and for iOS devices, the confidence level is either 0 (low), 1 (medium), or 2 (high). ### Data Collection Behavior On iOS, Avicenna wakes up every five minutes—unless it is terminated—to query all motion-based activities during the past five minutes. In the event of app termination, Avicenna will collect data from the most recent time it fetched such data. The only limitation is that the iOS provides data for the past seven days. --- sidebar_position: 7 --- # Screen State > Supported on Android & iOS. This data source records the time that the device's display turns on/off and the time that the device gets locked/unlocked. For each change in either the display state (on/off) or the lock state (locked/unlocked), a new record is created containing the previous state of whichever changed. The data source does not record the content of the screen or the reason for changes. It only captures the change and timing information. Each screen state record includes the following: **Record Time:** The time the previous state of the device had started. Internally stored as `record_time`. **End Time:** The time the previous state of the device had ended. Internally stored as `end_time`. **State:** Whether the display turned on or off. Internally stored as `state`. This is `true` if the display was on and `false` if the display was off. If the display state hasn't changed, this will be `null`. **Lock State:** Whether the device was locked or unlocked. Internally stored as `lock_state`. This is `locked` if the device was locked and `unlocked` if the device was unlocked. If the lock state hasn't changed, this will be `null`. ## Interpretation A given record of this data source looks like the following: ```json { "study_id": 1, "user_id": 2, "device_id": "2bae23410b7063ec", "record_time": 1606939056984, "end_time": 1606939060036, "state": true, "lock_state": null } ``` This means user ID 2 on device ID `2bae23410b7063ec`, turned on the device (state is `true`) at 1606939056984 (`2020-12-02 14:57:36.984-05:00`) and the device was on until 1606939060036 (`2020-12-02 14:57:40.036-05:00`). The `lock_state` is `null` because this record represents a change in the display state only and each record captures a change in either the display state or lock state, but not both. ### Consecutive Records with Duplicate State When exporting Screen State data, you may see consecutive entries with the same `State` (e.g., two "False" values). This occurs due to app lifecycle events in mobile operating systems. Sometimes, the Avicenna app is terminated and restarted during data collection. Mobile operating systems may kill background apps to conserve resources, then restart them later. When Avicenna restarts, it records the current screen state again, which may match the previously recorded state. For the purpose of data analysis, you can simply discard consecutive records with duplicate states and only use the first reported state. --- sidebar_position: 8 --- # Web Activity Tracking > Supported on Android only. This data source monitors participant web browsing activity using a specialized Firefox Nightly Mobile plugin. The collected data helps you understand: - Types of websites visited - Frequency of browsing sessions - Content of web pages viewed - Patterns in web usage behavior ## Setting Up Web Activity Tracking as a Data Source Ensure the following for using this data source: 1. You [contact us](mailto:support@avicennaresearch.com) for activation, due to privacy and compliance concerns. 2. Participants provide informed consent, understanding the data collection specifics. 3. Participants use Android devices. 4. [Firefox Nightly Mobile](https://play.google.com/store/apps/details?id=org.mozilla.fenix&hl=en_US) is installed on participant devices. 5. [The Research Web Capture plugin](https://addons.mozilla.org/en-US/android/addon/research-web-capture/) is installed on the Firefox Nightly Mobile app. 6. Participants have joined the relevant study in Avicenna. 7. Participants log in via the plugin interface using their Avicenna credentials. 8. Participants use only the designated device and Firefox Nightly Mobile app for web browsing during the study. ## Data Collection Behavior A record for the visited page is uploaded to Avicenna servers when the page loads. ## Monitoring Web Activity Tracking Data You can use [Kibana](../../analysis/kibana-basics/README.md) to monitor and download your data. ## Data Structure Besides [the common data fields](../README.md#common-data-fields), each record contains: **URL:** Full URL of the visited webpage. Internally stored as `url`. **Content:** HTML content of the page, converted to Markdown. Internally stored as `content`. ## Important Notes - Ensure participants understand the data collection process and provide informed consent. - The plugin respects privacy, collecting data only after the participant logs in. - Data collection from private browsing tabs can be excluded by participants. - Participants can stop data collection at any time by logging out of the plugin. # Background Data Collection Data collection from most data sources in Avicenna happens behind the scenes and without any participant involvement. After participants join your study and give consents, if your study involves any of the automated data sources, Avicenna will be continuously running on the participant's phone, capturing data, encrypting them, and uploading them to the server. While this is very useful to minimize the participants’ burden and prevent the Hawthorne effect, it goes against how most apps work. Both Android and iOS are designed such that when a user doesn't use an app very often, the operating system stops and terminates it. There are many factors which determine the condition and time based on which the operating system should terminate an app, including but not limited to: - How much resources (e.g. battery or processing power) is the app using? - The version of the Android or iOS. - How much battery has remained? - Is there any intensive important app currently running (e.g. Skype video call)? - Make and model of the phone. Based on these and other similar factors, Android and iOS might decide to terminate Avicenna in order to free space for other more important apps. This in turn leads to incomplete data for your study. We are always working to prevent app termination like this as much as possible. For the most parts, you need not to worry about the details. At the same time, there are a few items discussed below which are important to konw in order to improve the data quality. ## Keeping the Study Light One of the essential factors which cause an app to be terminated is the amount of resources it consumes. If the data sources which you monitor for your study generate lots of data, Avicenna will use more resources for storage, encryption, compaction, and upload. This, in turn, will increase the chances of app termination. Therefore, you need to to make sure your study only collects data from the necessary data sources. Not all data sources generate the same size of data. For example, the pedometer generates a record every time a step is captured, or GPS generates less than 50 records once every 5 minutes (a cycle). However, some data sources such as Accelerometer, Gyroscope, Magnetometer, and other software- or hardware-based motion sensors generate thousands of records per cycle. Using such data sources in your study can increase the chance of the app being terminated. In most cases, it's better to replace raw motion-sensor data (accelerometer, magnetometer, gyroscope, linear acceleration, gravity, and orientation) with their high-level equivalent data sources (motion-based activity recognition and pedometer). They can provide you with the data which are easier to analyze, and multiple orders of magnitude smaller in volume. Even if you have to collect raw motion-sensor data, you probably need either the raw data from hardware (i.e. accelerometer, magnetometer, and gyroscope) or software-based sensors (i.e. linear acceleration, gravity, and orientation). Collecting all these sensors is almost always unnecessary as the software-based sensors can be derived from the raw data from the hardware. ## Background Activity in iOS iOS is very strict on applications that perform background activity. In the App Store's App Review guidelines, Apple has defined a few categories, and only apps in those categories are allowed to perform any background activity. Unfortunately, research applications are not one of those categories, though location-aware applications are. In other words, while an application is actively using GPS, it can remain alive in the background and perform other tasks as well. Avicenna uses the category of "GPS-based apps" to remain active while not being visible. That means it requires actively using GPS in order to perform any task in the background. Therefore, if your study uses continuous monitoring of data sources, whether including GPS or not, Avicenna will ask the participant for GPS permission: ![Avicenna App for iOS Requesting GPS Permission for Background Activity](/assets/data-source-background-activity-ios-gps.png) If your study does monitor GPS, Avicenna will capture accurate GPS records and upload them periodically together with other data sources. If your study does not require GPS, Avicenna "pretends" to be using GPS by asking for very coarse GPS location, but it does not store nor upload those GPS data. This allows Avicenna to remain active in the background to record and upload other requested data sources while minimizing battery consumption. ### Reports Section of Avicenna iOS App To illustrate the location from which the Avicenna app has received the data, we have added a page to Avicenna iOS app called `Reports`. The `Report` page shows all the data points that have been seen by Avicenna, but not necessarily collected. As explained above, the location data are collected only if the study, you are participating in, explicitly requests for GPS data. Even in that case, the data uploaded and shared by researchers are based on the conditions defined in the consent form. Otherwise, the location data are received by the Avicenna app and is subsequently discarded, so neither Avicenna nor researchers have access to this information. ### Handling App Termination in iOS Avicenna in iOS automatically detects if it's been terminated by the iOS operating system or not. If yes, it shows a message to the user asking them to open Avicenna. Clicking that notification will simply open the Avicenna app which is enough for Avicenna to resume its operation. Avicenna only sends one notification when it detects the app is terminated. If the user discards this message, at the moment Avicenna will not send any additional reminder. If the user opens the Avicenna app and iOS terminates the app again, Avicenna will prompt another notification to the user. ![Avicenna App for iOS Notifies Participant After Termination](/assets/data-source-background-activity-reopen-ios.png) ## Background Activity in Android Android handles background applications differently than iOS. Therefore, the model described for Avicenna iOS does not apply to Android users. In Android, applications who wish to run continuously in the background are required to have a _Sticky Notification_: a permanent notification which is shown on the top of the screen is like normal Android notifications but cannot be dismissed by the user. ![Avicenna App for Android Showing a Sticky Notification](/assets/data-source-background-activity-android-sticky-notif.png) Such notifications tell Android "this application is performing an important task for the user, and it should not be terminated as long as possible". Sticky Notifications can be annoying for some users and might force them to drop out of the study. Therefore, Avicenna allows users to disable _Sticky Notifications_ through Avicenna Settings if they choose to. Of course, disabling _Sticky Notifications_ will make the app subject to termination by Android, and can impact the data collection for the study. While Avicenna informs the user about such impact, it respects their choice if they decide to disable _Sticky Notifications_. ![Avicenna App Allows Participants to Decide Whether Sticky Notifications Should be Used or Not](/assets/data-source-background-activity-android-sticky-notif-setting.png) ### Battery Optimization The behavior of the phones we explained above, where Android and iOS terminate the apps that are not used by the user recently, is called _Battery Optimization_. Android allows users to disable _Battery Optimization_ for their apps. When a participant joins your study using his or her Android phone, Avicenna shows them a notification and asks them to disable the Battery Optimization for the Avicenna app: ![Avicenna instructs participants to disable Battery Optimization](/assets/data-source-background-activity-android-battery-optimization-notification.png) Clicking on this notification will open the `Battery optimization` page. The participant should first open the dropdown on the top of the screen and select `All apps`: ![Battery Optimization screen - All apps option](/assets/data-source-background-activity-android-battery-optimization-all-apps.png) In the list of all apps, the participant should search and find Avicenna and tap on it, and then choose `Don't Optimize` in the dialog that opens. Pressing `Done` will save this setting and excludes Avicenna from battery optimization on this phone. This, in turn, will allow Avicenna to run and operate in the background as expected: ![Battery Optimization screen - Don't Optimize option](/assets/data-source-background-activity-android-battery-optimization-select-dont-optimize.png) While the above setting exists on all Android devices, not all Android manufacturers, such as Huawei or Samsung, respect these settings. Different manufacturers often have their settings to disable Battery Optimization. When the Avicenna app detects that it's not operating as expected, it assumes such manufacturer settings prevent the operation. Therefore, it shows instructions to the participants relative to the type of phone they are using. You can also find these manufacturer-specific settings in the following sections. --- sidebar_position: 1 --- # Android Battery Optimization Workarounds This article will help you find and exclude the Avicenna app from the battery optimization settings on various Android phones. While the settings are different depending on the device’s manufacturer, you can usually find these settings under Battery Optimization or Battery Saver. ## Samsung Depending on the Android version you are using on your Samsung device , you can follow the instructions below to allow the Avicenna app to work while not open. ### Android 11 On android 11, to keep the Avicenna app working properly in the background, there are two main settings that you should check. 1. Manage battery usage - Go to **Settings** -> **Apps** - Search for the **Avicenna app** and then click on **Battery** - Tap on **Optimize battery usage** - Switch to **All** apps listing - Find the **Avicenna app** and turn off **Battery optimization**. 2. Auto-optimize daily - Go to **Settings** -> **Battery and device care** - Click on the three dots menu, and then tap **Automation** - Make sure that **Auto-optimize daily** is disabled. ### Android 12 If your Samsung phone is running android 12, you should check 3 main settings to ensure the optimal operation of the Avicenna app. 1. Manage battery usage - Go to **Settings** -> **Apps** - Find the **Avicenna app** and tap **Battery** - Select **Unrestricted**. 2. Sleep mode - Go to **Settings** -> **Battery and device care** - Tap **Battery** -> **Background usage limits** - Disable **Put unused apps to sleep**. 3. Auto-optimize daily - Go to **Settings** -> **Battery and device care** - Click on the three dots menu and then tap **Automation** - Disable **Auto-optimize daily** and **Adaptive power saving**. ## Xiaomi On Xiaomi phones running Android 10 and above, the battery optimization functions are very restrictive and sometimes may keep the Avicenna app in sleep mode. For this reason, we recommend disabling battery optimization functions for the Avicenna app. This ensures optimal operation when the app is working in the background. ### Android 10 and above On your Xiaomi device, follow the instructions below to disable battery optimization. - Navigate to **Settings** -> **Apps** - Select **Manage Apps** - Find the **Avicenna app** and click on **Battery Saver** - From the options available, choose **No restrictions**. ## OnePlus Like many other android phones, OnePlus uses one of the most restrictive battery optimization functions. To disable this function on your OnePlus phone and ensure the optimal operation of the Avicenna app, follow these steps. ### Android 11 To make sure that the Avicenna app runs properly in the background, you should check 3 main settings: 1. Battery optimization settings - Go to **Settings** -> **Battery** -> **Battery Optimization** - Switch to **All apps** from the drop-down filter - Click on the **Avicenna app** and select **Don't optimize**. 2. Apps & Notification settings - Go to **Settings** -> **Apps & notifications** - Click on **Special app access** - Select the **Avicenna app** and switch off **Battery optimization**. 3. Sleep settings - Go to **Settings** -> **Battery** - Click on **Battery Optimization** - Tap the three dots menu and select **Advanced optimization** - Disable **Deep optimization** and Sleep **standby optimization**. ### Android 12 - Open phone **Settings** > **Apps** - Find the **Avicenna app** and click on **Battery usage** - Make sure that **Allow foreground activity**, **Allow background activity**, and **Allow auto-launch** are turned ON. ## Oppo Oppo phones have a built-in battery saving function that manages the battery usage of the apps installed on the device. However, as expected, these Battery Optimization settings terminate apps, such as the Avicenna app, that rely on background processing. To make sure that our app works without any restrictions in the background, follow these instructions. ### Android 11 If your Oppo phone is running android 11, you need to check 2 main settings: 1. Power saving mode - Go to **Settings** and tap on **Battery**. - Disable **Power saving mode** and **Super power saving mode**. 2. More battery settings - Open **Settings** - Go to **Battery** -> More battery settings - Tap **Optimize battery usage** - Find the **Avicenna app** and choose **Don't optimize**. ### Android 12 and 13 - Open your phone **Settings** - Select **Apps** and find the **Avicenna app** - Tap **Battery** and select **Unrestricted**. ## Huawei Traditionally, Huawei and their customized Android skin called EMUI has had one of the most restrictive background processing limitations. On default settings, background processing does not work right and apps working in background stop working. A possible workaround is to disable battery optimization. So if you have a Huawei phone, follow the steps below to let the Avicenna app run properly in the background. ### Android 10, 11, and 12 - Go to **Settings** -> **Apps** -> **Apps** - Tap on the three dots at the top of the screen and then on **Special access** - Select **Battery optimization** - Find the **Avicenna app**, and tap on **Don’t Allow** to disable battery optimization. ## Google Pixel By default, Pixel phones have the battery optimization function on, which allows apps to use the phone’s battery only when you need them to. This can get in the way of the Avicenna app working properly in the background. That’s why, we recommend that you follow the instructions below and disable battery optimization on your Pixel device. ### Android 11 There are 2 main settings to check on Pixel phones running android 11. 1. Battery Optimization settings - Open **Settings** -> **Battery** - Tap on the three dots menu, and then on **Battery Optimization** - Select the **Avicenna app** and make sure that it’s **Not optimized** - Go back to **Settings** -> **Apps & Notifications** - Click on **Advanced**, and then on **Special app access** - Tap **Battery optimization** and make sure that the **Avicenna app** is on the **Not optimized** list. 2. Adaptive Battery settings - Go to **Settings** and select **Battery** - Click on **Adaptive Battery** and then tap **disable**. ### Android 12 - Open **Settings** -> **Apps** - Find and click on the **Avicenna app** - Tap **Battery** and select **Unrestricted**. ## Sony Sony devices have their own unique feature called Stamina Mode. This mode, when enabled, prevents all the background processes to save battery consumption. To deactivate the Stamina Mode for the Avicenna app to work properly, - Go to **Settings** -> **Battery** -> **Stamina Mode** - Tap the switch to disable this function. There are also some other adjustments that you can make in the settings to ensure that the Avicenna app is not affected by aggressive battery optimization. - Go to **Settings** -> **Battery** - Tap the 3-dots menu in the top right corner - Select **Battery optimization** and then **Apps** - Find the **Avicenna app** and make sure that it's not being optimized to save battery. Additionally, you can make the Avicenna app exempt from the power saving feature. To do this, - Go to **Settings** ​-> **Apps & Notifications** - Select **Advanced** -​> **Special app access** -​> **Power saving feature** - Find the **Avicenna app** and switch to **Excepted**. --- sidebar_position: 2 --- # Android Background Permission Workarounds This guide provides instructions on how to configure various Android devices to allow the Avicenna app to run reliably in the background. ## Xiaomi Follow these steps to allow the Avicenna app to run in the background on Xiaomi devices. ### MIUI 10 (Android 6.0-9.0) 1. **Autostart** - Go to _Phone Settings_ > _Manage Apps_ > select **Avicenna**. - Enable **Autostart**. - For older phones: Open the **Security** app > _Permissions_ > enable **Autostart** for **Avicenna**. 2. **Background Permissions** - Go to _Phone Settings_ > _Manage Apps_ > select **Avicenna**. - Tap on **Permissions** and enable **Start in background**. ### MIUI 11 (Android 7.0-10.0) 1. **Autostart** - Go to _Phone Settings_ > _Apps_ > _Manage apps_ > select **Avicenna**. - Enable **Autostart** and confirm if prompted. 2. **Background Settings** - Go to _Phone Settings_ > _(Additional settings)_ > _Battery & performance_ > _Manage apps battery usage_. - Under _Saving power in the background_, tap on **Choose apps** > select **Avicenna**. - Under _Background settings_, select **No restrictions**. ### MIUI 12 (Android 9.0 – 11.0) 1. **Autostart** - Option 1: Open the **Security** App > _Permissions_ (or _Manage Apps_) > _Autostart_. Enable **Autostart** for **Avicenna**. - Option 2: Go to _Phone Settings_ > _Apps_ > _Manage apps_ > select **Avicenna** > enable **Autostart**. 2. **Auto-Remove Permissions** - Go to _Phone Settings_ > choose **Avicenna** > _App info_. - Go to **Permissions** > disable the option **Remove permissions if an app isn't used**. ### MIUI > 12 1. **Autostart** - Open the **Security** App. ![Security App](/assets/xiaomi-1.png) - Tap on **Permissions**. ![Permissions Screen](/assets/xiaomi-2.png) - Tap on **Autostart**. ![Autostart Screen](/assets/xiaomi-3.png) - Enable **Autostart** for the **Avicenna** app. 2. **Background Restriction** - Go to _Phone Settings_. ![Settings Screen](/assets/xiaomi-background-1.png) - Tap on **Battery & performance**. ![Battery & Performance Screen](/assets/xiaomi-background-2.png) - Tap on **Manage apps battery usage**. ![Manage Apps Battery Usage Screen](/assets/xiaomi-background-3.png) - Tap on **Choose apps**. ![Choose Apps Screen](/assets/xiaomi-background-4.png) - Select the **Avicenna** app. - Under _Background Settings_, tap **No restrictions**. ## OnePlus Follow these steps to allow the Avicenna app to run in the background on OnePlus devices. - Go to _Settings_ > tap **Advanced**. - Tap **Recent app management**. - Select **Normal clear** (This clears the task list and cache but should not clear background processes). ## Huawei Follow these steps to allow the Avicenna app to run in the background on Huawei devices. ### Android 7.x, 8.x - Open the **Phone Manager** app. - Swipe left and tap **Lock screen cleanup**. - Ensure **Avicenna** is set to **Don't close**. ### Android 9.x and above - Navigate to _Settings_. ![Settings Screen](/assets/huawei-1.png) - Tap on **Battery**. ![Battery Screen](/assets/huawei-2.png) - Find the **Avicenna** app in the list. - Disable **Manage Automatically** for **Avicenna**. - In the prompt that appears, ensure **Auto-launch**, **Secondary launch**, and **Run in background** are all enabled. ![App Launch Options](/assets/huawei-3.png) ### Protected Apps (e.g., Huawei Mate 8) - Go to _Settings_ from the Home screen. - Tap **Advanced Settings**. - Tap **Battery Manager**. - Tap **Protected apps**. - Enable the switch for **Avicenna** to register it as a protected app. ## Oppo Follow these steps to allow the Avicenna app to run in the background on Oppo devices. ### Android 9 - Go to _Phone Settings_ > _App Management_ > select **Avicenna**. - Enable **Allow Auto Startup**. - Tap **Power Saver** and select **Allow Background Running**. #### _For Oppo devices with a Security Center:_ - Go to _Phone Settings_ > _Security Centre_ > _Privacy Permissions_ > _Startup manager_. - Choose **Avicenna** and allow the app to run in the background. #### _On some Oppo devices (e.g., R9, R11, A37f):_ - Go to _Phone Settings_ > _Battery_ > _Others_. - Find **Avicenna** in the list and disable all battery-saving settings for it. #### _On some other Oppo devices:_ - Go to _Phone Settings_ > _Battery and storage_ > _Battery manager_. - Go to _Power consumption details_ > _Optimize for excessive power consumption_. - Find **Avicenna** in the list and disable the optimization switch. ### Android 10 1. **Background Mode** - Go to _Personalized/Personal energy saving_ settings for the **Avicenna** app. - Configure the following: - **Running in background**: Allow / Enable - **Prohibit running in background**: Disable - **Intelligently restrict running in background**: Disable 2. **Auto Start** - Path 1: Go to _Apps_ > _Security Center_ > _Privacy Permissions_ > _Auto-run management_ > enable **Avicenna**. - Path 2: Go to _Phone Settings_ > _Application Management_ > _Running_ tab > enable **Avicenna**. - Path 3: Go to _Phone Settings_ > _App Management_ > _Startup Management_ > choose **Allow Auto Startup**. ### Android 11 1. **Background Mode & Auto Start** - Go to _Phone Settings_ > _App management_ > select **Avicenna**. - Tap _Data usage details_ > enable **Background data**. - Go back to the **Avicenna** app settings page. - Tap _Battery usage_ and ensure the following are enabled: - **Allow foreground activity**: Enable - **Allow background activity**: Enable - **Allow auto launch**: Enable 2. **Disable Auto-Remove Permissions** - Go to _Phone Settings_ > **Avicenna** app settings. - Disable **Remove permissions when app is not used**. ### Android 12 1. **Background Mode** - Go to _Phone Settings_ > _Battery_. - Tap on **Save power** (or similar battery saving mode). - Enable the **Background activity** option for **Avicenna** (or ensure general background activity is not restricted). 2. **Auto Start** - Go to _Phone Settings_ > _Apps_ > _Auto launch_. - Choose **Avicenna** and enable the switch. 3. **Disable Auto-Remove Permissions** - Go to _Phone Settings_ > _Apps_ > choose **Avicenna**. - Disable **Remove permissions if app is unused**. - Go to **Permissions** > disable the option **Remove permissions and free up space**. ### Android 13 1. **Background Mode & Auto Start** - Go to _Phone Settings_ > _Apps_ > choose **Avicenna**. - Tap **Battery consumption** (or _Battery usage_). - Ensure the following are enabled: - **Allow foreground activity**: Enable - **Allow background activity**: Enable - **Allow automatic start** (or **Allow auto launch**): Enable 2. **Disable App Pausing** - Go to _Phone Settings_ > _Apps_ > choose **Avicenna**. - Disable **Pause app activity when not in use** (or similar). 3. **Disable Auto-Remove Permissions** - Go to _Phone Settings_ > _Apps_ > choose **Avicenna**. - Go to **Permissions**. - Disable the **Remove permissions and free up space** option. ### Newer Android versions (General Oppo) 1. **Background Mode** - Go to _Phone Settings_ > _App Management_ > choose **Avicenna**. - Tap **Power consumption protection** (or similar). - Select **Allow Background Running**. 2. **Lock the App in Recents** - Open the recent apps view (usually by swiping up from the bottom or tapping a dedicated button). - Find the **Avicenna** app preview. - Pull down on the **Avicenna** app preview (or tap a menu icon associated with it). - Tap the lock icon that appears. This prevents the system from closing the app when clearing recent apps. --- sidebar_position: 1 --- import SampleDataButton from '@site/src/components/sample-data-button'; # SensorKit [Apple SensorKit](https://developer.apple.com/documentation/sensorkit) provides access to rich sensor data from Apple devices, offering researchers detailed insights into raw data or metrics that the system processes from a sensor. This powerful framework enables the collection of data like device usage patterns, keyboard metrics, ambient light readings, pedometer data, and more. :::info SensorKit data collection is available on iPhones and iPads running iOS 14.0+ or iPadOS 14.0+ and Apple Watches paired to these devices. Individual data types may require newer iOS versions, which are specified in their respective sections. ::: ## Adding SensorKit As a Data Source Access to SensorKit data is limited to research uses and requires a private entitlement, which Apple reviews separately for each study. To add SensorKit as a data source to your study, please [contact our support team](mailto:support@avicennareasearch.com). These are the main steps that should be done in the process: - A custom iOS application will be developed for your study (you can also have a custom Android application, but it's not required). This is because our main application is designed to support all studies. For more details, you can check [our Branding documentation](../../../study-setup-and-deployment/branding.md). - After your custom iOS application is published in the App Store, it will have a Bundle ID. - Then, you should fill out an entitlement request document with Bundle ID, what data sources your study is going to collect and why, etc. Also, you should attach the Institutional Review Board (IRB) approval to the document. For more detailed information about the SensorKit access process, visit [Apple's Research & Care guide](https://www.researchandcare.org/resources/accessing-sensorkit-data/). ## Supported SensorKit Metrics in Avicenna Below is a comprehensive list of SensorKit metrics that Avicenna supports. We'll first cover the common fields that appear across all SensorKit data types, followed by the specific fields for each individual metric: ### Common Fields Across All SensorKit Data Sources #### Device Basic information about the device providing sensor data. Internally stored as part of each SensorKit record and includes: - **Name:** Device name (e.g., "John's iPhone"). Internally stored as `name`. - **Model:** Device model identifier (e.g., "iPhone14,3" for iPhone 13 Pro Max). Internally stored as `model`. - **System Name:** Operating system name (e.g., "iOS"). Internally stored as `system_name`. - **System Version:** OS version number (e.g., "16.5.1"). Internally stored as `system_version`. - **Product Type (iOS 17.0+):** Device category. Internally stored as `product_type`. #### Source Device Type - **Source Device Type:** Type of device providing the measurement: - `UNKNOWN` (0) - `IPHONE` (1) - `WATCH` (2) - `IPAD` (3) - `OTHER` (4) ### SensorKit Ambient Light Provides information about environmental lighting conditions. Internally stored as `sensorkit_ambient_light` and includes: - **Illuminance Lux:** Describes the sample's luminous flux. Internally stored as `illuminance_lux`. - **Chromaticity X:** Describes light brightness and tint x-value. Internally stored as `chromaticity_x_value`. - **Chromaticity Y:** Describes light brightness and tint y-value. Internally stored as `chromaticity_y_value`. - **Placement:** Sensor location on the device. Internally stored as `placement`. It can be one of the following: - `PLACEMENT_UNKNOWN` (0) - `FRONT_TOP` (1) - `FRONT_BOTTOM` (2) - `FRONT_RIGHT` (3) - `FRONT_LEFT` (4) - `FRONT_TOP_RIGHT` (5) - `FRONT_TOP_LEFT` (6) - `FRONT_BOTTOM_RIGHT` (7) - `FRONT_BOTTOM_LEFT` (8) ### SensorKit Pedometer Tracks pedestrian-related activity like steps taken and distance traveled. Internally stored as `sensorkit_pedometer` and includes: - **Start Date:** The start time for the pedometer data. Internally stored as `start_date`. - **End Date:** The end time for the pedometer data. Internally stored as `end_date`. - **Steps:** The number of steps taken by the user. Internally stored as `steps`. - **Distance:** The estimated distance traveled by the user in meters. Internally stored as `distance`. - **Average Active Pace:** The average pace of the user, measured in seconds per meter. Internally stored as `avg_active_pace`. - **Current Pace:** The current pace of the user, measured in seconds per meter. Internally stored as `current_pace`. - **Current Cadence:** The rate at which steps are taken, measured in steps per second. Internally stored as `current_cadence`. - **Floors Ascended:** The approximate number of floors ascended by walking. Internally stored as `floors_ascended`. - **Floors Descended:** The approximate number of floors descended by walking. Internally stored as `floors_descended`. ### SensorKit Heart Rate Captures heart rate measurements in beats per minute (BPM) with associated confidence levels. Internally stored as `sensorkit_heart_rate` and includes: - **Heart Rate:** The heart rate value in units of beats per minute (BPM). Internally stored as `heart_rate`. - **Confidence:** The confidence level of the heart rate measurement. Internally stored as `confidence`. It can be one of the following: - `CONFIDENCE_UNKNOWN` (0) - `CONFIDENCE_LOW` (1) - `CONFIDENCE_MEDIUM` (2) - `CONFIDENCE_HIGH` (3) - `CONFIDENCE_HIGHEST` (4) ### SensorKit Accelerometer Measures device acceleration. Internally stored as `sensorkit_accelerometer` and includes: - **X-Axis:** X-axis acceleration in G's (gravitational force). Internally stored as `x_axis`. - **Y-Axis:** Y-axis acceleration in G's (gravitational force). Internally stored as `y_axis`. - **Z Axis:** Z-axis acceleration in G's (gravitational force). Internally stored as `z_axis`. - **Identifier:** Unique measurement identifier. Internally stored as `identifier`. :::note Data is downsampled to 32Hz (default is 100Hz). [Contact our support team](mailto:support@avicennareasearch.com) for custom sampling rate adjustments. ::: ### SensorKit Rotation Rate Tracks device rotation. Internally stored as `sensorkit_rotation_rate` and includes: - **X-Axis:** Rotation rate around the x-axis. Internally stored as `x_axis`. - **Y-Axis:** Rotation rate around the y-axis. Internally stored as `y_axis`. - **Z-Axis:** Rotation rate around the z-axis. Internally stored as `z_axis`. :::note Data is downsampled to 32Hz (default is 100Hz). [Contact our support team](mailto:support@avicennareasearch.com) for custom sampling rate adjustments. ::: ### SensorKit Ambient Pressure Measures atmospheric pressure. Internally stored as `sensorkit_ambient_pressure` and includes: - **Identifier:** Unique measurement identifier. Internally stored as `identifier`. - **Pressure:** Atmospheric pressure measurement in hectopascals (hPa). Internally stored as `pressure_hpa`. - **Temperature:** Associated temperature measurement in Celsius. Internally stored as `temp_celsius`. ### SensorKit Message Usage Report Provides information about the use of the Messages app. Internally stored as `sensorkit_message_usage_report` and includes: - **Duration:** Report period in seconds. Internally stored as `duration_sec`. - **Total Incoming Messages:** Count of received messages. Internally stored as `total_incoming_messages`. - **Total Outgoing Messages:** Count of sent messages. Internally stored as `total_outgoing_messages`. - **Total Unique Contacts:** Number of distinct contacts. Internally stored as `total_unique_contacts`. ### SensorKit Phone Usage Report Reports the amount of time that the user is on phone calls. Internally stored as `sensorkit_phone_usage_report` and includes: - **Duration:** Report period in seconds. Internally stored as `duration_sec`. - **Total Incoming Calls:** Number of calls the user receives. Internally stored as `total_incoming_calls`. - **Total Outgoing Calls:** Number of calls the user makes. Internally stored as `total_outgoing_calls`. - **Total Phone Call Duration:** Total duration of phone calls in seconds. Internally stored as `total_phone_call_duration`. - **Total Unique Contacts:** Number of distinct contacts. Internally stored as `total_unique_contacts`. ### SensorKit Device Usage Report The frequency and relative duration that the user uses their device, particular Apple apps, or websites. Internally stored as `sensorkit_device_usage_report` and includes: - **Duration:** The duration that the report spans in seconds. Internally stored as `duration_sec`. - **Total Screen Wakes:** The total number of screen wakes for the device. Internally stored as `total_screen_wakes`. - **Total Unlocks:** The total number of unlocks for the device. Internally stored as `total_unlocks`. - **Total Unlock Duration:** The duration of time the device is in an unlocked state in seconds. Internally stored as `total_unlock_duration_sec`. - **Algorithm Version (iOS 16.4+):** The version of the algorithm that the system uses to generate the report. Internally stored as `algorithm_version`. - **App Usage By Category:** A list that describes the user's app activity over a period of time grouped by category. Internally stored as `app_usage_by_category`. - **Category Key:** Categories of apps, notifications, or websites. Internally stored as `category_key`. It can be one of the following: - `CATEGORY_UNKNOWN` (0) - `BOOKS` (1) - `BUSINESS` (2) - `CATALOGS` (3) - `DEVELOPER_TOOLS` (4) - `EDUCATION` (5) - `ENTERTAINMENT` (6) - `FINANCE` (7) - `FOOD_AND_DRINK` (8) - `GAMES` (9) - `GRAPHICS_AND_DESIGN` (10) - `HEALTH_AND_FITNESS` (11) - `KIDS` (12) - `LIFESTYLE` (13) - `MEDICAL` (14) - `MISCELLANEOUS` (15) - `MUSIC` (16) - `NAVIGATION` (17) - `NEWS` (18) - `NEWS_STAND` (19) - `PHOTO_AND_VIDEO` (20) - `PRODUCTIVITY` (21) - `REFERENCE` (22) - `SHOPPING` (23) - `SOCIAL_NETWORKING` (24) - `SPORTS` (25) - `STICKERS` (26) - `TRAVEL` (27) - `UTILITIES` (28) - `WEATHER` (29) - **App Usage:** Per-app usage details. Internally stored as `app_usage`. - **Bundle Identifier:** The bundle identifier of the app in use (if available). Internally stored as `bundle_identifier`. - **Report App Identifier (iOS 15.0+):** A pseudonym for a real application identifier. Internally stored as `report_app_identifier`. - **Supplemental Categories (iOS 16.4+):** Categories that provide more information about an app. Internally stored as `supplemental_categories`. - **Identifier:** List of unique identifiers for the supplemental category. Internally stored as `identifier`. - **Usage Time:** The amount of time the user uses the app in seconds. Internally stored as `usage_time_sec`. - **Relative Start Time (iOS 16.4+):** The time the user starts the app relative to the start time of the first app in a report interval in seconds. Internally stored as `relative_start_time_sec`. - **Text Input Sessions (iOS 15.0+):** List of text input session types that occur during application usage. Internally stored as `text_input_sessions`. - **Session Identifier:** A unique identifier for the keyboard session. Internally stored as `session_identifier`. - **Duration:** The length of time, in seconds, that the session spans. Internally stored as `duration_sec`. - **Session Type:** Methods to input text during a session. Internally stored as `session_type`. It can be one of the following: - `TYPE_UNKNOWN` (0) - `KEYBOARD` (1) - `THIRD_PARTY_KEYBOARD` (2) - `PENCIL` (3) - `DICTATION` (4) - **Notification Usage By Category:** List of the frequency of notifications per category. Internally stored as `notification_usage_by_category`. - **Category Key:** Application category. Internally stored as `category_key`. It can be one of the values same as the `Category Key` above. - **Notification Usage:** Per-notification details. Internally stored as `notification_usage`. - **Bundle Identifier:** The bundle identifier of the app that corresponds to the notification. Internally stored as `bundle_identifier`. - **Event:** The way that the user interacts with the notification. Internally stored as `event`. It can be one of the following: - `EVENT_UNKNOWN` (0) - `RECEIVED` (1) - `DEFAULT_ACTION` (2) - `SUPPLEMENTARY_ACTION` (3) - `CLEAR` (4) - `CLEAR_ALL` (5) - `REMOVED` (6) - `HIDE` (7) - `LONG_LOOK` (8) - `SILENCE` (9) - `APP_LAUNCH` (10) - `EXPIRED` (11) - `BANNER_PULL_DOWN` (12) - `TAP_COALESCE` (13) - `DEDUPED` (14) - `DEVICE_ACTIVATED` (15) - `DEVICE_UNLOCKED` (16) - **Web Usage By Category:** The amount of time the user accesses domains per category. Internally stored as `web_usage_by_category`. - **Category Key:** Website category. Internally stored as `category_key`. It can be one of the values same as the `Category Key` above. - **Web Usage:** Per-category web usage. Internally stored as `web_usage`. - **Total Usage Time:** The amount of web usage time that the report spans. Internally stored as `total_usage_time_sec`. ### SensorKit Visits Provides information about frequently visited locations. Internally stored as `sensorkit_visits` and includes: - **Identifier:** A value that maps to a unique geographic location. Internally stored as `identifier`. - **Arrival Start Date:** The start date of time within which the user arrives at a location of interest. Internally stored as `arrival_start_date`. - **Arrival End Date:** The end date of time within which the user arrives at a location of interest. Internally stored as `arrival_end_date`. - **Departure Start Date:** The start date of time within which the user departs from a location of interest. Internally stored as `departure_start_date`. - **Departure End Date:** The end date of time within which the user departs from a location of interest. Internally stored as `departure_end_date`. - **Distance from Home:** The location's distance from the home-category location in meters. Internally stored as `distance_from_home`. - **Location Category:** Type of location. Internally stored as `location_category`. It can be one of the following: - `LOCATION_UNKNOWN` (0) - `HOME` (1) - `WORK` (2) - `SCHOOL` (3) - `GYM` (4) ### SensorKit On-Wrist State Tracks Apple Watch wear patterns. Internally stored as `sensorkit_on_wrist_state` and includes: - **Crown Orientation:** A value that indicates the direction the Digital Crown (of Apple Watch) faces with respect to the user. Internally stored as `crown_orientation`. It can be one of the following: - `ORIENTATION_LEFT` (0) - `ORIENTATION_RIGHT` (1) - `ORIENTATION_UNKNOWN` (2) - **On Wrist:** Whether the watch is currently being worn. Internally stored as `on_wrist`. - **Wrist Location:** Which wrist the watch is worn on. Internally stored as `wrist_location`. It can be one of the following: - `LOCATION_LEFT` (0) - `LOCATION_RIGHT` (1) - `LOCATION_UNKNOWN` (2) - **On Wrist Date (iOS 17.0+):** The Timestamp when the watch was put on the wrist. Internally stored as `on_wrist_date`. - **Off Wrist Date (iOS 17.0+):** Timestamp when the watch was removed from the wrist. Internally stored as `off_wrist_date`. ### SensorKit Wrist Temperature Provides wrist temperature while the user sleeps. Internally stored as `sensorkit_wrist_temperature` and includes: - **Temperature:** The temperature sensor value in Celsius. Internally stored as `temperature_celsius`. - **Error Estimate:** An estimate of the amount of error in the temperature measurement in Celsius. Internally stored as `error_estimate`. The error could be in either positive or negative direction. - **Conditions:** The conditions of the measurement that impact its accuracy. Internally stored as `conditions`. It can be one of the following: - `CONDITION_UNKNOWN` (0) - `CONDITION_OFF_WRIST` (1) - `CONDITION_ON_CHARGER` (2) - `CONDITION_IN_MOTION` (3) ### SensorKit Siri Speech Metrics > iOS 17.0+ These metrics provide details about the user's voice, such as tenor, pitch, cadence, and speech timing, which includes words per minute and the average duration between words. This sensor doesn't provide raw audio data. For user privacy, SensorKit removes any transcript strings from the result. Internally stored as `sensorkit_speech_metrics` and includes: - **Session Identifier:** An identifier for the audio session. Internally stored as `session_identifier`. - **Time Since Audio Start (iOS 17.2+):** The number of seconds since the start of the audio stream in seconds. Internally stored as `time_since_audio_start`. - **Audio Level:** The audio level of the speech if available. Internally stored as `audio_level`. - **Loudness:** The measure of the audio level in decibels. Internally stored as `loudness`. - **Start Time Range:** The start time of the audio stream that the level applies to in seconds. Internally stored as `start_time_range_sec`. - **End Time Range:** The end time of the audio stream that the level applies to in seconds. Internally stored as `end_time_range_sec`. - **Speech Recognition Results:** The partial or final results of the speech recognition request (if available). Internally stored as `speech_recognition_results`. - **Best Transcription:** The transcription with the highest confidence level. Internally stored as `best_transcription`. - **Formatted String:** The entire transcription of utterances, formatted into a single, user-displayable string. Internally stored as `formatted_string`. - **Segments:** An array of transcription segments that represent the parts of the transcription, as identified by the speech recognizer. Internally stored as `segments`. - **Substring:** The string representation of the utterance in the transcription segment. Internally stored as `substring`. - **Alternative Substrings:** An array of alternate interpretations of the utterance in the transcription segment. Internally stored as `alternative_substrings`. - **Substring Range Lower Bound:** The lower bound of the substring range in the transcription segment. Internally stored as `substring_range_lower_bound`. - **Substring Range Upper Bound:** The upper bound of the substring range in the transcription segment. Internally stored as `substring_range_upper_bound`. - **Confidence:** The level of confidence the speech recognizer has in its recognition of the speech transcribed for the segment. Internally stored as `confidence`. - **Timestamp:** The start time of the segment in the processed audio stream. Internally stored as `timestamp`. - **Duration:** The number of seconds it took for the user to speak the utterance represented by the segment. Internally stored as `duration`. - **Transcriptions:** An array of potential transcriptions, sorted in descending order of confidence. Internally stored as `transcriptions`. This contains the same fields as the `Best Transcription` above. - **Is Final:** A Boolean value that indicates whether speech recognition is complete and whether the transcriptions are final. Internally stored as `is_final`. - **Metadata:** Contains the metadata results for a speech recognition request (if available). Internally stored as `metadata`. - **Average Pause Duration:** The average pause duration between words, measured in seconds. Internally stored as `average_pause_duration`. - **Speaking Rate:** The number of words spoken per minute. Internally stored as `speaking_rate`. - **Speech Duration:** The duration in seconds of speech in the audio. Internally stored as `speech_duration`. - **Speech Start Timestamp:** The start timestamp of speech in the audio. Internally stored as `speech_start_timestamp`. - **Voice Analytics:** An analysis of the transcription segment's vocal properties (if available). Internally stored as `voice_analytics`. - **Voicing:** The likelihood of a voice in each frame of a transcription segment. Internally stored as `voicing`. - **Frame Duration:** The duration of the audio frame in seconds. Internally stored as `frame_duration`. - **Acoustic Feature Value Per Frame:** An array of feature values, one value per audio frame, corresponding to a transcript segment of recorded audio. Internally stored as `acoustic_feature_value_per_frame`. - **Pitch:** The highness or lowness of the tone (fundamental frequency) in each frame of a transcription segment, expressed as a logarithm. Internally stored as `pitch`. It contains the same fields as the `Voicing` above. - **Jitter:** The variation in pitch in each frame of a transcription segment, expressed as a percentage of the frame's fundamental frequency. Internally stored as `jitter`. It contains the same fields as the `Voicing` above. - **Shimmer:** The variation in vocal volume stability (amplitude) in each frame of a transcription segment, expressed in decibels. Internally stored as `shimmer`. It contains the same fields as the `Voicing` above. - **Sound Classification:** The highest-ranking classifications in the time range (if available). Internally stored as `speech_classification`. - **Start Time Range:** The start time span that corresponds to the result's classifications. Internally stored as `start_time_range`. - **End Time Range:** The end time span that corresponds to the result's classifications. Internally stored as `end_time_range`. - **Classifications:** A sorted array of the request's top classification candidates. Internally stored as `classifications`. - **Identifier:** A prediction label that's one of the classifications a sound classifier's underlying model defines. Internally stored as `identifier`. - **Confidence:** The confidence value the model has in its prediction. Internally stored as `confidence`. - **Speech Expression:** The metrics and voice analytics for the range of speech (if available). Internally stored as `speech_expression`. - **Start Time Range:** The start time in the audio stream that the metrics and analytics apply to. Internally stored as `start_time_range`. - **End Time Range:** The end time in the audio stream that the metrics and analytics apply to. Internally stored as `end_time_range`. - **Version:** The version of the algorithm that the system uses to generate the metrics and analytics. Internally stored as `version`. - **Confidence:** The level of confidence of the speaker. Internally stored as `confidence`. - **Mood:** An indication of how slurry, tired, or exhausted the speaker sounds compared to normal speech. Internally stored as `mood`. - **Valence:** The degree of positive or negative emotion or sentiment of the speaker. Internally stored as `valence`. - **Activation:** The level of energy or activation of the speaker. Internally stored as `activation`. - **Dominance:** The degree of how strong or meek the speaker sounds. Internally stored as `dominance`. ### SensorKit Telephony Speech Metrics > iOS 17.0+ Provides data describing speech during phone calls. See [SensorKit Siri Speech Metrics](#sensorkit-siri-speech-metrics) for detailed field descriptions. ### SensorKit Keyboard Metrics Provides information about keyboard usage. Internally stored as `sensorkit_keyboard_metrics` and includes: - **Duration:** Duration of keyboard usage in seconds. Internally stored as `duration_sec`. - **Keyboard Identifier:** The identifier of the keyboard in the keyboard list. Internally stored as `keyboard_identifier`. - **Version:** The version of keyboard metrics. Internally stored as `version`. - **Width:** The width, in millimeters, of the keyboard in the report. Internally stored as `width_mm`. - **Height:** The height, in millimeters, of the keyboard in the report. Internally stored as `height_mm`. - **Input Modes (iOS 15.0+):** List of The active keyboard languages in the session. Internally stored as `input_modes`. - **Session Identifiers (iOS 16.4+):** List of identifiers for the keyboard sessions that report metrics to the sample. Internally stored as `session_identifiers`. - **Total Words:** The total number of typed words for the keyboard. Internally stored as `total_words`. - **Total Altered Words:** The total number of words that were modified. Internally stored as `total_altered_words`. - **Total Taps:** The total number of key taps. Internally stored as `total_taps`. - **Total Drags:** The total number of drag gestures. Internally stored as `total_drags`. - **Total Deletes:** The total number of delete operations. Internally stored as `total_deletes`. - **Total Emojis:** The total number of emojis used. Internally stored as `total_emojis`. - **Total Paths:** The total number of swipe-typing paths. Internally stored as `total_paths`. - **Total Path Time:** The total time to complete paths for the keyboard in seconds. Internally stored as `total_path_time_sec`. - **Total Path Length:** The total length of completed paths for the keyboard in centimeters. Internally stored as `total_path_length_cm`. - **Total Auto Corrections:** The total number of automatic corrections. Internally stored as `total_auto_corrections`. - **Total Space Corrections:** The total number of corrections made using the space key. Internally stored as `total_space_corrections`. - **Total Retro Corrections:** The total number of retroactive corrections. Internally stored as `total_retro_corrections`. - **Total Transposition Corrections:** The total number of corrections of transposed characters. Internally stored as `total_transposition_corrections`. - **Total Insert Key Corrections:** The total number of corrections using insert key. Internally stored as `total_insert_key_corrections`. - **Total Skip Touch Corrections:** The total number of skipped touch corrections. Internally stored as `total_skip_touch_corrections`. - **Total Near Key Corrections:** The total number of corrections of nearby key presses. Internally stored as `total_near_key_corrections`. - **Total Substitution Corrections:** The total number of character substitution corrections. Internally stored as `total_substitution_corrections`. - **Total Hit Test Corrections:** The total number of hit test corrections for the keyboard. Internally stored as `total_hit_test_corrections`. - **Total Typing Duration:** Overall time spent typing in seconds. Internally stored as `total_typing_duration_sec`. - **Total Path Pauses (iOS 15.0+):** The total number of pauses while drawing a path for a word. Internally stored as `total_path_pauses`. - **Total Pauses (iOS 15.0+):** The total number of pauses during the session. Internally stored as `total_pauses`. - **Total Typing Episodes (iOS 15.0+):** The total number of continuous typing episodes during the session. Internally stored as `total_typing_episodes`. - **Touch Down Up:** The duration between touch-down to touch-up for any key in milliseconds. Internally stored as `touch_down_up_ms`. - **Distribution Sample Values:** An array of sample values from the probability distribution. Internally stored as `distribution_sample_values` - **Touch Up Down (iOS 16.4+):** The duration between key release and next press in milliseconds. Internally stored as `touch_up_down_ms`. It contains the same fields as the `Touch Down Up` above. - **Space Touch Down Up:** The time between space key press and release in milliseconds. Internally stored as `space_touch_down_up_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Space Key:** The duration between consecutive space key presses in milliseconds. Internally stored as `space_to_space_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Delete Key:** The duration between the touch-up of the Space bar and the touch-down of a sequential Delete key in milliseconds. Internally stored as `space_to_delete_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Char Key:** The duration between the touch-up of the Space bar and the touch-down of a character key in milliseconds. Internally stored as `space_to_char_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Shift Key:** The time from space to shift key in milliseconds. Internally stored as `space_to_shift_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Plane Change Key:** The time from space to keyboard plane changes in milliseconds. Internally stored as `space_to_plane_change_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Prediction Key:** The time from space to prediction selection in milliseconds. Internally stored as `space_to_prediction_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Space to Path:** The time from space to swipe-typing in milliseconds. Internally stored as `space_to_path_ms`. It contains the same fields as the `Touch Down Up` above. - **Space Up Error Distance:** The upward touch accuracy error for the space key in millimeters. Internally stored as `space_up_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Space Down Error Distance:** The downward touch accuracy error for the space key in millimeters. Internally stored as `space_down_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Delete Touch Down Up:** The time between the delete key press and release in milliseconds. Internally stored as `delete_touch_down_up_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Space Key:** The time from delete to space key in milliseconds. Internally stored as `delete_to_space_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Delete:** The time between single delete key presses in milliseconds. Internally stored as `delete_to_delete_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Deletes:** The time between multiple delete presses in milliseconds. Internally stored as `delete_to_deletes_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Char Key:** The time from delete to character keys in milliseconds. Internally stored as `delete_to_char_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Shift Key:** The time from delete to shift key in milliseconds. Internally stored as `delete_to_shift_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Plane Change Key:** Time from delete to keyboard plane changes in milliseconds. Internally stored as `delete_to_plane_change_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete to Path:** Time from delete to swipe-typing in milliseconds. Internally stored as `delete_to_path_ms`. It contains the same fields as the `Touch Down Up` above. - **Delete Up Error Distance:** Upward touch accuracy error for delete key in millimeters. Internally stored as `delete_up_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Delete Down Error Distance:** Downward touch accuracy error for delete key in millimeters. Internally stored as `delete_down_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Char Key to Space Key:** Time from character to space key in milliseconds. Internally stored as `char_key_to_space_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Char Key to Delete:** Time from character to delete key in milliseconds. Internally stored as `char_key_to_delete_ms`. It contains the same fields as the `Touch Down Up` above. - **Char Key to Plane Change Key:** Time from character to keyboard plane changes in milliseconds. Internally stored as `char_key_to_plane_change_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Char Key to Prediction:** Time from character to prediction selection in milliseconds. Internally stored as `char_key_to_prediction_ms`. It contains the same fields as the `Touch Down Up` above. - **Char Key to Any Tap Key:** Time from character to any key tap in milliseconds. Internally stored as `char_key_to_any_tap_ms`. It contains the same fields as the `Touch Down Up` above. - **Short Word Char Key Touch Down Up:** Press-release time for short word characters in milliseconds. Internally stored as `short_word_char_key_touch_down_up_ms`. It contains the same fields as the `Touch Down Up` above. - **Short Word Char Key to Char Key:** Time between characters in short words in milliseconds. Internally stored as `short_word_char_key_to_char_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Short Word Char Key Up Error Distance:** Upward touch accuracy error in short words in millimeters. Internally stored as `short_word_char_key_up_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Short Word Char Key Down Error Distance:** Downward touch accuracy error in short words in millimeters. Internally stored as `short_word_char_key_down_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Any Tap to Char Key:** Time from any tap to character key in milliseconds. Internally stored as `any_tap_to_char_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Any Tap to Plane Change Key:** Time from any tap to plane change in milliseconds. Internally stored as `any_tap_to_plane_change_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Plane Change Key to Char Key:** Time from plane change to character key in milliseconds. Internally stored as `plane_change_key_to_char_key_ms`. It contains the same fields as the `Touch Down Up` above. - **Plane Change to Any Tap:** Time from plane change to any tap in milliseconds. Internally stored as `plane_change_key_to_any_tap_ms`. It contains the same fields as the `Touch Down Up` above. - **Path to Space:** The duration between the touch-up of a path and the touch-down of a sequential Space bar in Milliseconds. Internally stored as `path_to_space_ms`. It contains the same fields as the `Touch Down Up` above. - **Path to Delete:** The duration between the touch-up of a path and the touch-down of a sequential Delete key in Milliseconds. Internally stored as `path_to_delete_ms`. It contains the same fields as the `Touch Down Up` above. - **Path to Path:** Time between consecutive paths in milliseconds. Internally stored as `path_to_path_ms`. It contains the same fields as the `Touch Down Up` above. - **Up Error Distance:** General upward touch accuracy error in millimeters. Internally stored as `path_up_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Down Error Distance:** General downward touch accuracy error in millimeters. Internally stored as `path_down_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Long Word Touch Down Up:** Distribution of press-release times for long words in milliseconds. Internally stored as `long_word_touch_down_up_ms`. It contains the same fields as the `Touch Down Up` above. - **Long Word Touch Down Down:** Distribution of times between presses in long words in milliseconds. Internally stored as `long_word_touch_down_down_ms`. It contains the same fields as the `Touch Down Up` above. - **Long Word Up Error Distance:** The distance from the touch-up to the center of the intended key of the characters of a long word in millimeters. Internally stored as `long_word_up_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Long Word Down Error Distance:** The distance from the touch-down to the center of the intended key of the characters of a long word in millimeters. Internally stored as `long_word_down_error_distance_mm`. It contains the same fields as the `Touch Down Up` above. - **Touch Down Down:** Time between consecutive key presses in milliseconds. Internally stored as `long_word_touch_down_down_ms`. It contains the same fields as the `Touch Down Up` above. - **Path Typing Speed (iOS 15.0+):** The QuickType words per minute in the session. Internally stored as `path_typing_speed_words_per_min`. - **Typing Speed Char (iOS 15.0+):** The user's typing rate in characters per second. Internally stored as `typing_speed_char_per_sec`. - **Path Error Distance Ratio:** List of sample values of the ratio of error distance between the intended and actual path. Internally stored as `path_error_distance_ratio`. - **Word Count Sentiments:** Analyzes the emotional content of typed words and provides counts for different sentiment categories. Internally stored as `word_count`. Possible values are: - `ABSOLUTIST` (0): Words expressing absolute or black-and-white thinking (e.g., "always", "never") - `DOWN` (1): Words indicating feeling down or depressed - `DEATH` (2): References to death, dying, or mortality - `ANXIETY` (3): Words expressing worry, fear, or anxiety - `ANGER` (4): Words conveying anger, frustration, or aggression - `HEALTH` (5): References to health, illness, or medical conditions - `POSITIVE` (6): Words expressing optimism, joy, or positive emotions - `SAD` (7): Words indicating sadness or grief - `LOW_ENERGY` (8): Words suggesting fatigue, exhaustion, or low motivation - `CONFUSED` (9): Words expressing confusion, uncertainty, or disorientation - `CATEGORY_UNKNOWN` (10): Words that don't fit into other sentiment categories - **Emoji Count Sentiments:** Tracks the frequency of emoji usage categorized by emotional sentiment, providing insight into non-verbal emotional expression in digital communication. Uses the same sentiment categories as `Word Count Sentiments`. ## Data Collection Behavior Avicenna's SensorKit implementation operates within the app's primary data collection cycle (1-minute active collection every 5 minutes) to efficiently gather sensor data from iOS devices. During each active collection window, the framework fetches data using a sophisticated dual-cycle approach: most sensors operate on 8-hour collection windows, while high-frequency sensors (accelerometer and rotation) use 1-hour windows repeated 8 times before cycling to the next sensor. This design optimizes data collection while managing the system resources. The framework intelligently tracks the last successful fetch for each sensor-device combination to ensure continuous data coverage, implementing automatic downsampling to 32Hz for high-frequency sensors to maintain data quality while minimizing storage requirements. When the app enters its 1-minute collection window, SensorKit initiates fetch requests for any pending data since the last successful fetch, ensuring seamless integration with Avicenna's broader data collection strategy while adhering to iOS's privacy and performance guidelines. ## Monitoring SensorKit Data You can export and download the collected SensorKit data using [the Data Export page](../../../analysis/raw-data#exporting-raw-data). import SampleDataButton from '@site/src/components/sample-data-button'; # Fitbit Integrating Fitbit's health metrics with Avicenna's research tools can provide a comprehensive view of individual well-being, allowing for more accurate health analyses and personalized care plans. This section explains how Fitbit integrates with Avicenna, making it easier for researchers to understand and use the health-related data of their participants. ## Supported Fitbit Metrics in Avicenna In this section, we list the comprehensive range of Fitbit metrics that Avicenna supports. ### Fitbit Activity Summary Provides a summary of a user's daily activities. It is stored internally as `fitbit_daily_activity`, and includes the following fields: - **Record Time:** Start time of the day the summary pertains to. Internally recorded as `record_time`. - **Activity Calories:** Calories burned during active periods throughout the day. Internally recorded as `activity_calories`. - **Calories:** Total calories burned, including BMR, tracked activity, and manual logs. Internally recorded as `calories`. - **BMR Calories:** Number of BMR calories. Internally recorded as `calories_bmr`. - **Distance:** Estimated daily distance traveled, measured in meters. Internally recorded as `distance`. - **Elevation:** Change in altitude throughout the day, measured in meters. Internally recorded as `elevation`. - **Floors:** Approximate number of floors climbed. Internally recorded as `floors`. - **Sedentary Duration:** The cumulative duration of the participant being sedentary over the day, measured in minutes. Internally stored as `minutes_sedentary`. - **Lightly Active Duration:** The cumulative duration of the participant being lightly active over the day, measured in minutes. Internally stored as `minutes_lightly_active`. - **Fairly Active Duration:** The cumulative duration of the participant being fairly active over the day, measured in minutes. Internally stored as `minutes_fairly_active`. - **Very Active Duration:** The cumulative duration of the participant being very active over the day, measured in minutes. Internally stored as `minutes_very_active`. - **Steps:** Number of steps taken. Internally recorded as `steps`. ### Fitbit Activity Intraday Offers a snapshot of the user’s activity in 1-minute intervals. This is internally stored in the `fitbit_activity` table. The available fields for this metric are: - **Record Time:** Starting time of the interval for which the data is recorded. Internally stored as `record_time`. - **Calories:** Total calories burned, including BMR, tracked activities, and manually logged exercises during the time interval. Internally stored as `calories`. - **Distance:** Estimated distance in meters traversed by the participant within the time interval. Internally stored as `distance`. - **Elevation:** Estimated change in vertical height in meters during the time interval. Internally stored as `elevation`. - **Floors:** Approximate number of floors ascended by the participant throughout the time interval. Internally stored as `floors`. - **Sedentary Duration:** Total time in minutes the participant was sedentary during the time interval. Internally stored as `minutes_sedentary`. - **Lightly Active Duration:** Cumulative time in minutes the participant was lightly active throughout the time interval. Internally stored as `minutes_lightly_active`. - **Fairly Active Duration:** Cumulative time in minutes the participant was moderately active throughout the time interval. Internally stored as `minutes_fairly_active`. - **Very Active Duration:** Cumulative time in minutes that the participant was intensely active throughout the time interval. Internally stored as `minutes_very_active`. - **Steps:** Total number of steps taken by the participant during the time interval. Internally stored as `steps`. ### Fitbit Sleep It contains details about the user's sleep patterns. It is internally recorded in the `fitbit_sleep` database table, and includes these fields: - **Start Time:** Start time of the sleep log. Internally recorded as `start_time`. - **End Time:** End time of the sleep log. Internally recorded as `end_time`. - **Log Type:** Type of sleep log based on the detection method, either auto-detected or manually logged. Internally recorded as `log_type`. The following values are included: - `auto_detected`: Automatically detected by the sleep detection service. - `manual`: Logged or edited manually by the user. - **Duration:** Total length of the sleep log, measured in seconds. Internally recorded as `duration_sec`. - **Efficiency:** The sleep efficiency score, is calculated out of 100. Internally recorded as `sleep_efficiency`. - **Main Sleep:** A boolean value indicating if the log pertains to the main sleep session of the day. Internally recorded as `is_main_sleep`. - **After Wake Duration:** Total number of minutes the user remained awake after initially waking up. Internally recorded as `minutes_after_wakeup`. - **Asleep Duration:** Total number of minutes the user was asleep. Internally recorded as `minutes_asleep`. - **Awake Duration:** Total number of minutes the user was awake during the sleep session. Internally recorded as `minutes_awake`. - **To Fall Sleep Duration:** Time in minutes it took for the user to fall asleep. This is generally 0 for auto-detected sleep logs. Internally recorded as `minutes_to_fall_sleep`. - **In-Bed Duration:** Total time in minutes the user spent in bed. Internally recorded as `minutes_in_bed`. ### Fitbit Heart Rate This metric includes the heart-rate-related data. It is recorded internally as `fitbit_heart_rate`, and includes these fields: - **Record Time:** When the heart rate value was recorded. Internally recorded as `record_time`. - **Heart Rate:** Heart rate value during the day in BPM. Internally recorded as `heart_rate`. ### Fitbit Weight Log This metric contains the user's weight logs. It is stored internally as `fitbit_weight_log`, and includes these fields: - **Weight:** The weight value in kilograms. Internally recorded as `weight`. - **BMI:** The Body Mass Index value. Internally recorded as `bmi`. - **Fat:** The fat percentage. Internally recorded as `fat`. If it is not available, this field will not be present. - **Source:** The source of the weight data. `API` means data originated from a 3rd party integration using the Web API, the data was manually entered into the Fitbit mobile or web application, or the data recorded by a predefined scale was manually edited. `Aria` means the data originated from an Aria or Aria 2 scale. `AriaAir` means the data originated from an Aria Air scale. `Withings` means the data originated from a Withings scale. Internally recorded as `source`. ## Data Collection Behavior Whenever there is new Fitbit data, the Fitbit's server will send the new data to Avicenna. ## Adding Fitbit As a Data Source See [Accessing Data Sources](../../data-sources/README.md#accessing-data-sources). ## Monitoring Fitbit Data There are two ways to monitor and export Fitbit data: [using the Data Export page](../../analysis/raw-data#exporting-raw-data) and [using Kibana](../../analysis/kibana-basics/#avicenna-kibana-integration). ## Fitbit Data Source in Participant App After a participant joins a study, they need to grant access to Avicenna to collect data. To do that, the participant needs to go to `Settings` on the Avicenna app and click on `My Studies`. Then they should choose the study that is collecting Fitbit data. On the study's page, clicking on the `Data Sources` will take them to the data sources page: ![Study's Data Sources page in the Avicenna app](/assets/fitbit-study-data-sources-page-avicenna-app.png) On this page, the participant will see all of the data sources that the study uses to collect data. Among these data sources, on the corner of the Fitbit data source(s), there is a `Grant Access` button: ![Granting access to Fitbit on the Data Sources page](/assets/fitbit-study-data-sources-page-grant-access.png) By clicking on the `Grant Access` button, the participant will be directed to the sign-in page of the Fitbit official website. Then, they can decide what information is going to be shared with Avicenna: ![Selecting which Fitbit metrics to grant access to](/assets/fitbit-granting-access-to-different-metrics.png) :::note Checking the `Allow All` check box and then pressing the `Allow` button, will allow Avicenna to collect all kinds of data from Fitbit, in case the researcher added another metric to the study. ::: After clicking on Allow, the participant will be redirected to the Data Sources page of the study in the Avicenna app, and they have successfully granted access to Avicenna to gather Fitbit data. The participants can stop sharing the data anytime by clicking on `Revoke Access` on the Data Sources page. ![Revoking access in the Avicenna app](/assets/fitbit-revoking-access-in-avicenna-app.png) # Garmin Garmin wearables are considered ideal devices for recording digital biomarkers in health and clinical research. They are popular among consumers and therefore can increase participant retention, and also their devices provide a wide range of sensors and physiological metrics. Most importantly, unlike some widely-known competitors, they are very supportive in helping health research and clinical trials by providing necessary SDK and API to access the detailed data. At Avicenna, we support all Garmin wearables. You can integrate them into your study with just a few clicks and start collecting data from any of their sensors or calculated metrics. In this section we will cover: - The health features that Garmin devices offer, - The types of data that they collect, and - The Garmin Connect app. ## Garmin Health Features Aside from the hardware-based sensors, Garmin devices come with many health and wellness monitoring features (or calculated metrics). These features can help the end user improve and monitor their health. These features include: - **Body Battery:** This feature is designed to help manage body’s resources throughout the day. It provides metric to determine when is the best time for physical activities. It also shows the user how relaxation, exercise, and stress impact the state of the body. - **Stress Tracking:** The all-day stress tracking feature manages and tracks the stress levels throughout the day. It can also warn the user when the stress level is unusually high. - **Sleep Tracking:** This feature monitors the quantity and quality of the sleep patterns, such as sleep times and sleep stages. - **Heart Rate Monitoring** monitors and analyzes the heart rate. - **Pulse Oxygen Sensor** measures how much oxygen is in the blood during waking and sleeping hours. - **Calories Tracking** helps tracking the calories that the body burns during the day. - **Hydration Tracking:** Based on the user's gender, this feature sets a default daily hydration goal and allows tracking the progress towards that goal. - **Workout Modes:** Garmin offers a wide range of workout modes through its Garmin Connect app. - **Fitness Age** estimates user's overall fitness compared to his or her actual age. ## The Data that Garmin Devices Collect Garmin devices collect two types of data: - **Personal Data:** To create and sign in to your account, Garmin asks for your personal data such as your name, email address, and your location. They also use this information to send you personalized support and safety information related to your Garmin devices. - **Body-Related Data:** They collect a variety of body-related data, including your heart rate, stress, sleep patterns, pulse OX, and physical activities. ## Garmin Connect According to Garmin, Garmin Connect is: > The tool for tracking, analyzing, and sharing health and fitness activities from your Garmin device. It’s basically the name of the Garmin’s app which users should use to interact with the data from their wearable device. The app offers further features, including: - **Detailed Health Data:** The app provides you with detailed information about your health and performance stats, activities, and training. You can also track your sleep, heart rate, stress level, and other health data. - **Join Challenges:** The app leverages gamification techniques such as physical activity challenges to motivate you to be more active. These challenges include walking, hiking, biking, and also the weekly steps challenge. - **Social Components:** Through its News Feed, the Garmin Connect adds a social dimension to the physical activities and exercises. --- sidebar_position: 1 --- import SampleDataButton from '@site/src/components/sample-data-button'; # Different Metrics that Garmin Devices Collect Garmin has a wide range of wearables, each collecting different metrics. All these metrics can be categorizes into the following: - Garmin Health Daily - Garmin Health - Garmin Health Heart - Garmin Health Sleep Daily - Garmin Health Sleep - Garmin Health Body Composition - Garmin Health Stress - Garmin Health User Metrics - Garmin Health Pulse Ox - Garmin Health Respiration If you want to use Garmin wearable data in your study, you should decide which of these categories you want to collect. The Avicenna app then asks the participant for the relevant permission, and collects the relevant data from the Garmin servers. The following sections explain each of these categories, and the type of data you can expect to receive from them. ## Garmin Health Daily Provides a high-level snapshot of a user's health information throughout a day. This corresponds to the information in Garmin Connect's "My Day" section. The following information is included in each Garmin Health Daily record: **Date** User's local calendar date the health information belongs to. Internally stored as `date`. **Start Time** Start time of the period. Internally stored as `start_time`. **Duration** Length of the day the data is collected. 86400 if a full day is collected or less if the user syncs mid-day. Internally stored as `duration_sec`. **Steps** Count of steps recorded during the monitoring period. Internally stored as `steps`. **Distance** Distance traveled in meters. Internally stored as `distance_meter`. **Active Time** The time (in seconds) during which the device wearer was considered active during the monitoring period. This is based on internal heuristics in each device. Internally stored as `active_time_sec`. **Active Kilocalories** Active Kilocalories (dietary calories) burned through actual movement and activity during the monitoring period. Internally stored as `active_kilocalories`. **BMR Kilocalories** BMR Kilocalories burned by existing Basal Metabolic Rate (calculated based on the user's height, weight, age, and other demographic data). Internally stored as `bmr_kilocalories`. **Consumed Calories** The number of calories consumed by the user through food for that day (value subtracted from calorie goal). This value is received from MyFitnessPal and is not entered within Connect. Internally stored as `consumed_calories`. **Moderate Intensity Duration** Cumulative duration of moderate-intensity activities that last at least 600 seconds at a time. An activity of moderate intensity is defined as one having a MET value between 3-6. Internally stored as `moderate_intensity_duration_sec`. **Vigorous Intensity Duration** The total duration of vigorous-intensity exercises that last at least 600 seconds at a time. An activity with a MET value greater than 6 is considered vigorous. Internally stored as `vigorous_intensity_duration_sec`. **Floors Climbed** The number of floors climbed during the monitoring period. Internally stored as `floors_climbed`. **Min Heart Rate** Minimum heart rate value captured during the monitoring period, in beats per minute. Internally stored as `min_heart_rate`. **Average Heart Rate** Average heart rate value captured during the last 7 days, in beats per minute. Internally stored as `average_heart_rate`. **Max Heart Rate** Maximum heart rate value captured during the monitoring period, in beats per minute. Internally stored as `max_heart_rate`. **Resting Heart Rate** Average heart rate at rest during the monitoring period, in beats per minute. Internally stored as `resting_heart_rate`. **Average Stress Level** An abstraction of the user's average stress level throughout the monitoring period, on a scale of 1 to 100, or -1 if there is insufficient data to calculate average stress. `Rest` (i.e. not stressful) is a score of 1 to 25, `low` stress is a score of 26-50, `medium` stress is 51-75, and `high` stress is a score of 76-100. Internally stored as `average_stress_level`. **Max Stress Level** The highest stress level measurement taken during this monitoring period. Internally stored as `max_stress_level`. **Stress Duration** The number of seconds during this monitoring period when stress levels were in the stressful range (26-100). Internally stored as `stress_duration`. **Rest Stress Duration** The number of seconds during this monitoring period during which stress levels were in the restful range (1 to 25). Internally stored as `rest_stress_duration`. **Activity Stress Duration** The number of seconds in this monitoring period where the user was engaged in physical activity and so stress measurement was unreliable. All duration in this monitoring period not covered by stress, rest, and activity stress should be considered `Uncategorized`, either because the device was not worn or because not enough data could be taken to generate a stress score. Internally stored as `activity_stress_duration`. **Low-Stress Duration** The portion of the user's stress duration where the measured stress score was in the low range (26-50). Internally stored as `low_stress_duration`. **Medium-Stress Duration** The portion of the user's stress duration where the measured stress score was in the medium range (51-75). Internally stored as `medium_stress_duration`. **High-Stress Duration** The portion of the user's stress duration where the measured stress score was in the high range (76-100). Internally stored as `high_stress_duration`. **Stress Qualifier** A qualitative label applied based on all stress measurements in this monitoring period. Possible values: `unknown`, `calm`, `balanced`, `stressful`, `very_stressful`, `calm_awake`, `balanced_awake`, `stressful_awake`, `very_stressful_awake`. This matches what the user will see in Garmin Connect. **Steps Goal** The user's steps goal for this monitoring period. Internally stored as `steps_goal`. **Net Kilocalories Goal** The user's goal for net caloric intake (consumed calories minus active calories) for this monitoring period. This field is related to integration with MyFitnessPal and may not be present for many users. Internally stored as `net_kilocalories_goal`. **Intensity Duration Goal** The user's goal for consecutive seconds of moderate to vigorous-intensity activity for this monitoring period. Internally stored as `intensity_duration_goal`. **Floors Climbed Goal** The user's goal for floors climbed in this monitoring period. Internally stored as `floors_climbed_goal`. ## Garmin Health Garmin Health records are provided with 15-minute time slice granularity. Each activity type monitored within a single time slice has its own record. For example, if the user sat for five minutes, walked for five minutes, and then ran for five minutes during the period of 15 minutes, three activity records would be generated for that single 15-minute time slice. The duration value would be 900 seconds for all three records, but the active time for each would be 300 seconds. A duration of less than 900 seconds indicates that the user synced data during the middle of a time slice. On the user's next sync, that time slice record will be replaced with a 900-second-duration epoch covering the entire span. Each Garmin Health record includes the following: **Activity Type** `Sedentary` when having a heart rate of less than 90 bpm, `Generic` when greater than 90 bpm but no movement is recorded. `Walking` when heart rate is greater than 90 bpm and movement is recorded. Internally stored as `activity_type_id`. **Start Time** Start time of the monitoring period. Internally stored as `record_time`. **Start Time Offset** Offset in seconds to add to `Start Time` to derive the `local` time of the device that captured the data. Internally stored as `start_time_offset_sec`. **Duration** Length of the monitoring period in seconds. Internally stored as `duration_sec`. **Active Time** The portion of the monitoring period (in seconds) in which the device wearer was active for this activity type. The sum of active times of all epochs of the same start time (and different activity types) should be equal to the duration. Internally stored as `active_time_sec`. **Steps** Count of steps recorded during the monitoring period. Internally stored as `steps`. **Distance** Distance traveled in meters. Internally stored as `distance_meter`. **Active Kilocalories** Active kilocalories (dietary calories) burned during the monitoring period. This includes only the calories burned by the activity and not calories burned as part of the basal metabolic rate (BMR). Internally stored as `active_kilocalories`. **MET** MET (Metabolic Equivalent of Task) value for the active time for this activity type. Metabolic Equivalent of Task (MET) is an official measure of activity intensity. Garmin's calculation of MET is an estimation based on the biometric data provided (height, weight, date of birth, gender) and improves in accuracy if heart rate data is also captured. Please refer to [MET and physical activity intensity](http://www.cdc.gov/nccdphp/dnpa/physical/pdf/PA_Intensity_table_2_1.pdf). for more detailed information. Internally stored as `met`. **Motion Intensity** A Qualitative measure of intensity. Motion Intensity is a numerical abstraction of low-level accelerometer data, provided for use in further analysis. Motion Intensity is calculated at minute-level granularity as a number between 0 and 7, with 0 being absolutely still and 7 being constant, sharp motion. Unlike steps, distance, or activity type, which take net movement into account, motion intensity will increase even if the user does not move in space. For instance, if a user were to jump up and down or fidget with a pencil they would not get credit for any distance, but their motion intensity scores for that monitoring period would increase. It is very common to see mid-range max motion intensities even for sedentary epochs as most people do not sit absolutely still. Internally stored as `intensity_type_id`. **Mean Motion Intensity** The average motion intensity scores for all minutes in this monitoring period. Internally stored as `mean_motion_intesity`. **Max Motion Intensity** The largest motion intensity score of any minute in this monitoring period. Internally stored as `max_motion_intesity`. ## Garmin Health Heart Each Garmin Health Heart record includes the following: **Heart Rate** Representative heart rate value recorded for the previous 15 seconds from record time, in beats per minute. Lack of entry for a given offset should be interpreted as no data available. Internally stored as `heart_rate`. ## Garmin Health Sleep Daily Each Garmin Health Sleep Daily record includes the following: **Date** User's local calendar date the health information belongs to. Internally stored as `date`. **Start Time** Start time of the period. Internally stored as `start_time`. **Duration** Length of the monitoring period in seconds. Internally stored as `duration`. **Unmeasurable Sleep** Time in seconds that the sleep level of the user could not be measured. This may or may not correspond to off-wrist time. Internally stored as `unmeasurable sleep`. **Deep Sleep Duration** Time in seconds the user spent in deep sleep during the sleep period. Internally stored as `deep sleep duration`. **Light Sleep Duration** Time in seconds the user spent in light sleep during the sleep period. Internally stored as `light_sleep_duration`. **REM Sleep** Time in seconds the user spent in REM sleep during the sleep period. Internally stored as `rem_sleep`. **Awake Duration** Time in seconds the user spent awake during the sleep period. Internally stored as `awake_duration`. **Validation** Validation state of the sleep data and its date range. The data could be auto-confirmed, but the sleep window could have been manually adjusted, or the sleep data itself is entirely manually entered. Values: `MANUAL`, `DEVICE`, `AUTO_TENTATIVE`, `AUTO_FINAL`, `AUTO_MANUAL`, `ENHANCED_TENTATIVE`, `ENHANCED_FINAL`. Internally stored as `validation`. ## Garmin Health Sleep Each Garmin Health Sleep record includes the following: **Start Time** Start time of the period. Internally stored as `start_time`. **End Time** End time of the period. Internally stored as `end_time`. **Sleep Level** One of `Deep`, `Light`, and `Awake`. Internally stored as `sleep_level`. ## Garmin Health Body Composition Each Garmin Health Body Composition record includes the following: **Muscle Mass** Muscle mass in grams. Internally stored as `muscle_mass`. **Bone Mass** Bone mass in grams. Internally stored as `bone_mass`. **Body Water** Percentage of body water (range 0.0 - 100.0). Internally stored as `body_water`. **Body Fat** Percentage of body fat. (range 0.0 - 100.0). Internally stored as `body_fat`. **Body Mass Index** Body mass index, or BMI. Internally stored as `body_mass_index`. **Weight** Weight in grams. Internally stored as `weight`. ## Garmin Health Stress Each Garmin Health Stress record includes the following: **Stress Level** Stress level value recorded. Internally stored as `stress_level`. **Body Battery Level** Body battery level value recorded. Information on and a list of devices that support Body Battery is available [here](https://support.garmin.com/ms-MY/?faq=2qczgfbN00AIMJbX33dRq9) . Internally stored as `body_battery_level`. ## Garmin Health User Metrics Each Garmin Health User Metrics record includes the following: **Date** User's local calendar date the health information belongs to. Internally stored as `date`. Internally stored as `date`. **Vo2 Max** An estimate of the maximum volume of oxygen (in milliliters) the user can consume per minute per kilogram of body weight at maximum performance. Internally stored as `vo2_max`. **Fitness Age** An estimation of the 'age' of the user's fitness level, calculated by comparing internal fitness metrics with the average readings of biometrically similar users by age. For instance, a fitness age of 48 indicates that the user's physical fitness is similar to that of an average 48- year-old person of the same gender. Internally stored as `fitness_age`. ## Garmin Health Pulse Ox Each Garmin Health Pulse Ox record includes the following: **SpO2** SpO2 measurement taken at record time (1 sample/minute). Internally stored as `spo2`. **On Demand** A Boolean to show whether this pulse ox summary represents an on-demand reading or an averaged acclimation reading. Internally stored as `on_demand`. ## Garmin Health Respiration Each Garmin Health Respiration record includes the following: **Breaths** Respiration measurement taken at record time, in breaths per minute. Internally stored as `breaths`. --- position: 2 --- # Garmin Integration in Avicenna Participant App Using Garmin data source allows your study to collect data from any Garmin wearables. To do so, your participants need to have such devices and also create an account on the Garmin’s website. When a participant joins your study, Avicenna asks them to grant access to their Garmin account. Having this permission, Avicenna can access the Garmin wearable data, and make them accessible to you through the Researcher Dashboard. This section demonstrates how participants can grant access to their Garmin account through the Avicenna app. To grant access to Garmin data sources, first you participant needs to open the Avicenna app and tap on _Settings_ from the top-right corner. ![Avicenna App Settings](/assets/1-2.png) Once they are in the _Settings_, click on _My Studies_ and choose the study that they are currently participating in. ![Tap on My Studies from the Settings](/assets/2-3.png) ![Select Your Study](/assets/3-3.png) Next, tap on _Data Sources_ from the bottom-right. This takes them to a page where they can see a list of all the data sources being collected. ![The About Study Page](/assets/4-1.png) As shown in the screenshot below, this study is collecting one Garmin data source, _Garmin Health Respiration_: ![Data Sources](/assets/5.png) Your participant should press _Grant Access_, and then enter their Garmin account email and password. If they do not have an account already, they can create one by visiting the [Garmin website](https://www.garmin.com/en-US/account/). ![Enter Your Garmin Account Information](/assets/6-3.png) After entering your Garmin account information, click on _Sign In_. Following that, your participant can decide what information is going to be shared with Avicenna. They can also check what information is Avicenna sharing with their Garmin Connect account. If everything is OK, press _Save_. Note that your participant can disconnect from Avicenna at any time in their Garmin account settings. ![The Information Shared with Avicenna](/assets/7.png) In the next stage, click on _Agree_ to allow sharing information with Avicenna. ![Press Agree to Share Information with Avicenna](/assets/8.png) Finally, your participant will be directed back to the _Data Sources_ page. Note that to stop this sharing of data, they can simply tap on _REVOKE ACCESS_. ![Data Sources Page](/assets/9.png) # Hexoskin Integrating [Hexoskin's advanced biometric shirts](https://hexoskin.com/) with Avicenna offers researchers comprehensive physiological monitoring. This integration enables the collection of detailed cardiorespiratory, activity, and sleep data for in-depth health analysis and research insights. ## Supported Hexoskin Metrics in Avicenna :::info Reference Content For a detailed explanation on how these metrics are defined and collected, please refer to the [**Hexoskin API version 3.3.x**](https://api.hexoskin.com/docs/index.html). ::: :::important Important Note on Certain Metrics Some metrics, particularly those related to Heart Rate Variability (HRV) and Sleep Stages (e.g., `ANN`, `HRV_HF`, `HRV_LF`, `HRV_LF_NORMALIZED`, `HRV_TRIANGULAR`, `NN_INTERVAL`, `NN_OVER_RR`, `SDNN`, `SLEEP_PHASE`), require specific activity types like **Rest**, **Sleep**, or **5-Minute Rest Test** to be actively recorded or tagged for calculation. These activities **must be initiated by the participant using the Hexoskin mobile app** during the recording session or tagged later on the Hexoskin Dashboard. If these specific activities are not recorded/tagged, the dependent metrics will not be computed by Hexoskin servers and will therefore be **unavailable** in the data collected by Avicenna, even if the raw sensor data (like ECG) was captured. Ensure participants are instructed accordingly if these metrics are crucial for your study. ::: Below is a list of Hexoskin metrics supported in Avicenna. Each metric includes details about its parameters and sampling rates. - **Acceleration X:** Measures acceleration along the _x-axis_. Sampled at 64 Hz with 13-bit resolution (3.90625 mG) and a dynamic range of ±16G. Values are stored in _G/256_ units (divide by 256 to convert to G-force). Internally stored as `acceleration_x`. - **Acceleration Y:** Measures acceleration along the _y-axis_. Sampled at 64 Hz with 13-bit resolution (3.90625 mG) and a dynamic range of ±16G. Values are stored in _G/256_ units (divide by 256 to convert to G-force). Internally stored as `acceleration_y`. - **Acceleration Z:** Measures acceleration along the _z-axis_. Sampled at 64 Hz with 13-bit resolution (3.90625 mG) and a dynamic range of ±16G. Values are stored in _G/256_ units (divide by 256 to convert to G-force). Internally stored as `acceleration_z`. - **Activity:** Represents activity level based on accelerometer intensity. Calculated using a high-pass filter (2.65 Hz) on all three axes and averaged over the last second. Sampled at 1 Hz with 3.9 mG resolution and ±16G dynamic range. Values are stored in _G/256_ units (divide by 256 to convert to G-force). Internally stored as `activity`. - **ANN:** _Average NN Interval_. This is the average of valid `NN Interval` values (see below) over the last 5 minutes, measured in _seconds_. Calculated at 1/300 Hz. Internally stored as `ann`. - **Breathing Rate:** Measures respiratory frequency in _respirations per minute (RPM)_. Calculated as the average of the last 7 respirations, sampled at 1 Hz. Valid range is 2-60 RPM; values outside this range are clipped (values > 60 become 60, values < 2 become 2). Internally stored as `breathing_rate`. - **Breathing Rate Quality:** Assesses the quality of respiratory measurements. Updated at 1 Hz. Internally stored as `breathing_rate_quality`. It includes the following status flags (0 = false, 1 = true): - `RESP_STATUS_OK`: _Good quality respiratory signal._ - `RESP_STATUS_NO_A`: _Thoracic sensor disconnected (signal zero for 2 seconds)._ - `RESP_STATUS_NO_B`: _Abdominal sensor disconnected (signal zero for 2 seconds)._ - `RESP_STATUS_BASELINE_A`: _Thoracic baseline changed significantly._ - `RESP_STATUS_BASELINE_B`: _Abdominal baseline changed significantly._ - `RESP_STATUS_NOISY_A`: _Thoracic signal is noisy (high-frequency content)._ - `RESP_STATUS_NOISY_B`: _Abdominal signal is noisy (high-frequency content)._ - **Cadence:** Measures walking or running pace in _steps per minute_. Averaged over the last 7 strides using a low-pass filter (0.17 Hz), sampled at 1 Hz. Valid range is 30-240 steps per minute; values > 240 are clipped to 240, values < 30 are set to 0. Internally stored as `cadence`. - **Device Position:** Detects the orientation and placement of the smart garment using accelerometer data. Recorded asynchronously (only when position changes). Internally stored as `device_position`. Possible values: | Value | Device Position | | ----- | -------------------------------- | | 0 | _Undefined_ | | 1 | _Blue LED upward_ (y-axis up) | | 2 | _Blue LED downward_ (-y-axis up) | | 3 | _Face downward_ (z-axis up) | | 4 | _Face upward_ (-z-axis up) | | 5 | _Wire downward_ (x-axis up) | | 6 | _Wire upward_ (-x-axis up) | - **ECG 1:** Measures the electrical activity of the heart. Sampled at 256 Hz using a band-pass filter (1.6-33.9 Hz). Resolution is 6.4 μV, dynamic range is 26 mV. Values are stored in _μV _ 6.4\* units. Internally stored as `ecg_1`. - **Energy Mifflin-Keytel:** Estimates total energy expenditure based on ECG data using Mifflin and Keytel equations. Adjusted for user's weight, height, sex, and heart rate limits. Updated at 1 Hz, measured in _Watts_. Internally stored as `energy_mifflin_keytel`. - **Expiration:** Detects the start of the breathing cycle's exhalation phase. Calculated from thoracic and abdominal sensor data. Recorded asynchronously. Quality is assessed by `Breathing Rate Quality`. Internally stored as `expiration`. - **Heart Rate:** Measures real-time cardiac frequency in _beats per minute (BPM)_. Calculated as the average of the last 16 heartbeats based on RR intervals from ECG data. Updated at 1 Hz. Valid range is 30-220 BPM. Initialized at 70 BPM; maintains the last valid value during invalid detections. Quality is assessed by `Heart Rate Quality`. Internally stored as `heart_rate`. - **Heart Rate Quality:** Assesses the quality of heart rate measurements. Updated at 1 Hz. Internally stored as `heart_rate_quality`. Includes the following status flags (0 = false, 1 = true): - `ECG_STATUS_OK`: _ECG good quality._ - `ECG_FOR_FUTURE_USE`: _Reserved._ - `ECG_STATUS_DISCONNECTED`: _Shirt disconnected._ - `ECG_STATUS_50_60HZ`: _50-60 Hz noise dominant in ECG._ - `ECG_STATUS_SATURATED`: _ECG signal saturated._ - `ECG_STATUS_ARTIFACTS`: _Movement artifacts affecting RR intervals._ - `ECG_STATUS_UNRELIABLE_RR`: _ECG okay, but some RR intervals are unreliable (outside 30-220 BPM range)._ - **HRV HF:** _High-Frequency component_ of heart rate variability. Measures power in the 0.15-0.4 Hz range using valid NN intervals from the last 300 seconds. Calculated every 5 minutes (1/300 Hz). Measured in _milliseconds squared (ms²)_. Values are stored in _ms²/10_ units (divide by 10 for ms²). Returns 0 if insufficient valid intervals exist. Internally stored as `hrv_hf`. - **HRV LF:** _Low-Frequency component_ of heart rate variability. Measures power in the 0.04-0.15 Hz range using valid NN intervals from the last 300 seconds. Calculated every 5 minutes (1/300 Hz). Measured in _milliseconds squared (ms²)_. Values are stored in _ms²/10_ units (divide by 10 for ms²). Returns 0 if insufficient valid intervals exist. Internally stored as `hrv_lf`. - **HRV LF Normalized:** _Relative Low-Frequency power_ of heart rate variability. Calculated as the LF/(LF+HF) ratio using valid NN intervals from the last 300 seconds. Updated every 5 minutes (1/300 Hz). Values are stored in _1/10000_ units (divide by 10000 for the ratio). Returns 0 if insufficient valid intervals exist. Internally stored as `hrv_lf_normalized`. - **HRV Triangular:** Geometric measure of heart rate variability. Calculated as the triangular index of valid NN intervals over the last 5 minutes. Updated every 5 minutes (1/300 Hz). Values are stored in _percent_ units (divide by 100 for decimal). Internally stored as `hrv_triangular`. - **Inspiration:** Detects the start of the breathing cycle's inhalation phase. Calculated from thoracic and abdominal sensor data. Recorded asynchronously. Quality is assessed by `Breathing Rate Quality`. Internally stored as `inspiration`. - **Minute Ventilation:** Measures the volume of air exchanged per minute in _mL/min_. Calculated as the average volume inspired during the last 7 complete respiration cycles. Updated at 1 Hz. Values are stored in _mL/min _ 13.28\* units (divide by 13.28 for mL/min). Internally stored as `minute_ventilation`. - **Minute Ventilation Adjusted:** Personalized minute ventilation measurement in _cL/min_ (centiliters per minute). Calculated like `Minute Ventilation` but adjusted for the user profile. Updated at 1 Hz. Values are stored in _cL/min_ units (multiply by 10 for mL/min). Internally stored as `minute_ventilation_adjusted`. - **NN Interval:** Measures the duration between _normal_ consecutive heartbeats (QRS complexes), excluding unreliable intervals. Valid range is 0.265s to 4s. Updated asynchronously based on QRS detection. Values are stored in _second/256_ units (divide by 256 for seconds). Internally stored as `nn_interval`. - **NN Over RR:** Assesses heart rhythm regularity. Calculated as the ratio of normal intervals (NN) to all RR intervals over the last 5 minutes. Updated every 5 minutes (1/300 Hz). Measured in _percent_. Values are stored in _1/10000_ units (divide by 10000 for the ratio). Provides a quality score for HRV measurements. Internally stored as `nn_over_rr`. - **QRS:** Detects the ventricular depolarization pattern (heartbeat). Provides timestamps centered on the QRS complex. Updated asynchronously based on ECG data. Quality is assessed by `RR_interval_quality`. Note: QRS timing may have \>10 ms error; use `nn_interval` for more precision. Internally stored as `qrs`. - **Respiration:** Directly measures breathing movements (thoracic and abdominal) using Respiratory Inductance Plethysmography (RIP). Sampled at 128 Hz with 16-bit resolution. Estimated resolution is 8 mL. Note: _A decrease in raw value corresponds to an increase in volume._ Internally stored as `respiration`. - **RR Interval:** Measures the time between _any_ consecutive heartbeats (QRS complexes). Valid range is 0.265s to 4s. Updated asynchronously based on QRS detection. Values are stored in _second/256_ units (divide by 256 for seconds). Quality is assessed by `RR_interval_quality`. Internally stored as `rr_interval`. - **RR Interval Quality:** Assesses the quality of RR interval measurements. Updated asynchronously with each QRS detection. Internally stored as `rr_interval_quality`. Includes the following status flags (0 = false, 1 = true): - `RELIABLE_RR`: _QRS good quality._ - `NOISY_RR`: _QRS detected in noisy signal._ - `UNRELIABLE_RR`: _RR interval is unreliable (outside 30-220 BPM range or significantly different from recent intervals)._ - **SDNN:** Measures heart rate variability using the _Standard Deviation of NN intervals_. Calculated over the last 5 minutes using valid NN intervals. Updated every 5 minutes (1/300 Hz). Measured in _seconds_. Values are stored in _second/4096_ units (divide by 4096 for seconds). Internally stored as `sdnn`. - **Sleep Phase:** Identifies the current sleep stage (e.g., NREM, REM, WAKE) by analyzing activity, heart rate, and breathing rate. Updated asynchronously when the sleep phase changes. Internally stored as `sleep_phase`. Possible values: | Value | Sleep Phase | | ----- | -------------------------- | | 0 | _No Data_ | | 2 | _NREM_ (Non-REM) | | 5 | _REM_ (Rapid Eye Movement) | | 6 | _WAKE_ | - **Sleep Position:** Tracks body orientation during rest using accelerometer data. Updated asynchronously when position changes. Internally stored as `sleep_position`. Possible values: | Value | Sleep Position | | ----- | ----------------------------- | | 0 | _Undefined_ | | 1 | _Belly_ (blue LED upward) | | 2 | _Back_ (blue LED downward) | | 3 | _Right side_ (face downward) | | 4 | _Left side_ (face upward) | | 5 | _Standing_ (wire down/upward) | :::info Sleep positions assume the device is in the shirt pocket with the wire pointing up, the light facing out, and the device on the side of the body. ::: - **Step:** Monitors the continuous count of detected steps throughout the day. Updated asynchronously based on accelerometer data. Internally stored as `step`. - **Tidal Volume:** Measures the volume of air inhaled or exhaled during a normal breath in _milliliters (mL/inspiration)_. Updated at 1 Hz. Values are stored in _mL/min _ 13.28\* units (divide by 13.28 for mL/min). Represents the raw signal measurement. Internally stored as `tidal_volume`. - **Tidal Volume Adjusted:** Personalized measurement of breath volume in _milliliters (mL/inspiration)_, accounting for individual characteristics. Updated at 1 Hz. Values are stored in _mL_ units. Internally stored as `tidal_volume_adjusted`. ## Data Collection Behavior Hexoskin devices collect data continuously while the smart garment is worn. Data is stored locally on the device first. It must then be synchronized with Hexoskin's servers using the [**OneSync software**](https://hexoskin.com/pages/downloads) while the device is connected via USB to a computer. :::important While the **OneSync software** handles data synchronization, participants **must use the Hexoskin mobile app** if they need to manually start specific activities (like `Rest` or `Sleep`) during a recording session. Recording these specific activity types is necessary for the calculation of certain metrics, such as HRV and Sleep Stages (see note under [Supported Hexoskin Metrics](#supported-hexoskin-metrics-in-avicenna)). If these metrics are required for your study, ensure participants understand the need to use the mobile app to tag these activities. ::: Avicenna checks the Hexoskin servers every five minutes for new data and downloads it to the Avicenna platform. :::info Hexoskin devices generate a large amount of data. Depending on the collection duration and synchronization frequency, data availability in Avicenna might be delayed. ::: ## Adding Hexoskin As a Data Source Refer to [Accessing Data Sources](../../data-sources/README.md#accessing-data-sources) for instructions on adding Hexoskin. ## Monitoring Hexoskin Data You can export and download the collected Hexoskin data using [the Data Export page](../../analysis/raw-data#exporting-raw-data). ## Hexoskin Data Source in Participant App After joining a study, participants must grant Avicenna access to collect their Hexoskin data. 1. Open the Avicenna app and navigate to **Settings** > **My Studies**. 2. Select the study using Hexoskin data. 3. Tap on **Data Sources**. ![Study's Data Sources page in the Avicenna app](/assets/hexoskin-study-data-sources-page-avicenna-app.png) 4. Find the Hexoskin data source and tap the **Grant Access** button. ![Granting access to Hexoskin on the Data Sources page](/assets/hexoskin-study-data-sources-page-grant-access.png) 5. You will be redirected to the Hexoskin website to sign in and authorize Avicenna. ![Granting access to Hexoskin on the Hexoskin website](/assets/hexoskin-website-grant-access-to-all-metrics.png) 6. Click **Allow**. You will be sent back to the Avicenna app's Data Sources page. Access has now been granted. Participants can stop sharing data at any time by returning to the **Data Sources** page for the study and tapping **Revoke Access**. ![Revoking access to Hexoskin on the Data Sources page](/assets/hexoskin-study-data-sources-page-revoke-access.png) # Polar Health metrics from [Polar wearables](https://www.polar.com/) can offer detailed insights into individual health metrics, including heart rate, sleep, and exercise data. This section explains how Polar integrates with Avicenna, making it easier for researchers to understand and use the health data of their participants. ## Supported Polar Metrics in Avicenna In this section, we list the comprehensive range of Polar metrics that Avicenna supports. ### Polar Exercise Provides detailed information about exercise sessions. It is stored internally as `polar_exercise` and includes the following fields: - **Record Time:** Calculated by combining `start_time` with `duration`, stored as milliseconds since epoch. Internally recorded as `record_time`. - **Device:** The specific Polar device used during the exercise. Internally recorded as `device`. - **Start Time:** The start time of the exercise session. Internally recorded as `start_time`. - **UTC Offset:** The offset from UTC at the start of the exercise, measured in minutes. Internally recorded as `start_time_offset_minutes`. - **Duration:** The total duration of the exercise session, specified in ISO 8601 format. Internally recorded as `duration`. - **Calories:** Total kilocalories expended during the training session. Internally recorded as `calories`. - **Distance:** Total distance traveled during the exercise, measured in meters. Internally recorded as `distance`. - **Heart Rate:** Information about heart rate metrics during the exercise, including: - **Average Heart Rate:** The average heart rate across the session. Internally recorded under `heart_rate.average`. - **Maximum Heart Rate:** The peak heart rate achieved during the session. Internally recorded under `heart_rate.maximum`. - **Training Load:** The overall training load impact of the exercise session. Internally recorded as `training_load`. - **Sport:** The type of sport or activity performed. Internally recorded as `sport`. - **Has Route:** Indicates if there is route data available for the session. Internally recorded as `has_route`. - **Club ID:** ID for the club associated with the session, if relevant. Internally recorded as `club_id`. - **Club Name:** Name of the club linked to the exercise. Internally recorded as `club_name`. - **Detailed Sport Info:** Detailed description of the sport as per Polar Flow compatibility. Internally recorded as `detailed_sport_info`. - **Fat Percentage:** Percentage of exercise calories derived from fat. Available if supported by the device. Internally recorded as `fat_percentage`. - **Carbohydrate Percentage:** Percentage of exercise calories derived from carbohydrates. Available if supported by the device. Internally recorded as `carbohydrate_percentage`. - **Protein Percentage:** Percentage of exercise calories derived from protein. Available if supported by the device. Internally recorded as `protein_percentage`. - **Running Index:** Score calculated from heart rate and speed data collected via GPS or stride sensor during running. Internally recorded as `running_index`. - **Heart Rate Zones:** Detailed list of times spent in various heart rate zones: - **Index:** The position of the zone in the list. Internally recorded as `index`. - **Lower Heart Rate Limit:** The minimum heart rate of the zone. Internally recorded as `lower_limit`. - **Upper Heart Rate Limit:** The maximum heart rate of the zone. Internally recorded as `upper_limit`. - **Time Spent In Zone:** Duration spent in this zone, formatted in ISO 8601. Internally recorded as `in_zone`. - **Samples:** Comprehensive list of all exercise samples collected: - **Recording Rate:** Frequency of sample recording in seconds, applicable only where relevant. Internally recorded as `recording_rate`. - **Sample Type:** Type of the sample, e.g., heart rate, speed. Internally recorded as `sample_type`. - **Data:** Comma-separated list of sample values. Internally recorded as `data`. - **Route:** List of geographical data points collected during the exercise: - **Latitude:** Latitude in degrees. Internally recorded as `latitude`. - **Longitude:** Longitude in degrees. Internally recorded as `longitude`. - **Time:** Timestamp for each location point, formatted as duration. Internally recorded as `time`. - **Satellites:** Number of satellites detected, up to a maximum of 63. Internally recorded as `satellites`. - **Fix:** GPS fix status, with a maximum value of three. Internally recorded as `fix`. - **Training Load Pro:** Advanced metrics to assess training load: - **Date:** The specific date of the training session. Internally recorded as `date`. - **Cardio Load:** Cardiovascular effort quantified. Internally recorded as `cardio_load`. - **Muscle Load:** Muscular effort quantified. Internally recorded as `muscle_load`. - **Perceived Load:** Subjectively rated effort of the training session. Internally recorded as `perceived_load`. - **Cardio Load Interpretation** Interpretations of the cardio loads. Internally recorded as `perceived_load_interpretation`. - **Muscle Load Interpretation** Interpretations of the muscle loads. Internally recorded as `muscle_load_interpretation`, ``. - **Perceived Load Interpretation** Interpretations of perceived loads. Internally recorded as `perceived_load_interpretation`. - **User RPE:** Rated Perceived Exertion, quantifying internal training load. Internally recorded as `user_rpe`. ### Polar Sleep Provides detailed information about sleep sessions. It is stored internally as `polar_sleep` and includes the following fields: - **Record Time:** Considered `sleep_end_time`, stored as milliseconds since epoch. Internally recorded as `record_time`. - **Date:** The date on which the sleep occurred. Internally recorded as `date`. - **Sleep Start Time:** The start time of the sleep period in ISO-8601 date/time format. Internally recorded as `sleep_start_time`. - **Sleep End Time:** The end time of the sleep period in ISO-8601 date/time format. Internally recorded as `sleep_end_time`. - **Continuity:** An estimate of how continuous the sleep was, on a scale from 1.0 to 5.0, where 5.0 indicates uninterrupted sleep. Internally recorded as `continuity`. - **Continuity Class:** Verbal assessments of sleep continuity ranging from `FRAGMENTED_SLEEP` to `VERY_CONTINUOUS_SLEEP`. Internally recorded as `continuity_class`. - **Light Sleep:** Total time in seconds spent in the light sleep stages (N1 + N2) between falling asleep and waking up. Internally recorded as `light_sleep`. - **Deep Sleep:** Total time in seconds spent in the deep sleep stage (N3) between falling asleep and waking up. Internally recorded as `deep_sleep`. - **REM Sleep:** Total time in seconds spent in the REM sleep stage between falling asleep and waking up. REM stands for rapid eye movement. Internally recorded as `rem_sleep`. - **Unrecognized Sleep Stage:** Total time in seconds spent in unrecognized sleep stages, often due to inadequate sensor contact or positioning. Internally recorded as `unrecognized_sleep_stage`. - **Sleep Score:** Summarizes the amount and quality of sleep into a single number on a scale from 1 to 100, consisting of multiple components including sleep time and sleep depth. Internally recorded as `sleep_score`. - **Total Interruption Duration:** The total time in seconds spent awake between falling asleep and waking up. Internally recorded as `total_interruption_duration`. - **Sleep Charge:** Sleep score compared to the usual level over the past 28 days, with a scale from `MUCH_BELOW_USUAL` to `MUCH_ABOVE_USUAL`. Internally recorded as `sleep_charge`. - **Sleep Goal:** Time goal in seconds for sleep, based on age-related sleep duration recommendations. Internally recorded as `sleep_goal`. - **Sleep Rating:** The quality of sleep, ranging from `VERY_POORLY` to `VERY_WELL`, with `NO_VALUE` indicating no value given. Internally recorded as `sleep_rating`. - **Short Interruption Duration:** Total time in seconds of short interruptions in sleep lasting less than 90 seconds. Internally recorded as `short_interruption_duration`. - **Long Interruption Duration:** Total time in seconds of long interruptions in sleep lasting 90 seconds or more. Internally recorded as `long_interruption_duration`. - **Sleep Cycles:** Number of complete sleep cycles recorded during the sleep session. Internally recorded as `sleep_cycles`. - **Group Duration Score:** Evaluates sleep duration against preferred settings and age-related recommendations, scored from 1.0 to 100.0 and categorized as poor, moderate, or good. Internally recorded as `group_duration_score`. - **Group Solidity Score:** Averages component scores of long interruptions, continuity, and actual sleep, rated from 1.0 to 100.0 and categorized as poor, moderate, or good. Internally recorded as `group_solidity_score`. - **Group Regeneration Score:** Averages scores of REM and deep sleep components, rated from 1.0 to 100.0 and interpreted as poor, moderate, or good regeneration. Internally recorded as `group_regeneration_score`. - **Hypnogram:** Classified time spans of sleep stages in 30-second epochs, covering light, deep, REM, unrecognized, or wake stages. Internally recorded under `hypnogram`. - **Time:** Timestamp for each stage, formatted as hour and minute. - **Stage:** Sleep stage identified at each timestamp. Values can be `WAKE`, `REM`, `LIGHTER_NON_REM`, `LIGHT_NON_REM`, `DEEP_NON_REM`, or `UNKNOWN`. - **Heart Rate Samples:** 5-minute average samples of heart rate during the sleep period. Samples may occasionally be recorded more frequently than every 5 minutes. Internally recorded under `heart_rate_samples`. - **Time:** Timestamp for each heart rate sample, formatted as hour and minute. - **Heart Rate:** Heart rate in beats per minute at each sample time. ### Polar Continuous Heart Rate It enables a more accurate measurement of daily calorie consumption and overall activity. It is stored internally as `polar_continuous_heart_rate` and includes the following fields: - **Record Time:** The timestamp when the heart rate data was received from Polar Webhook, stored as milliseconds since epoch. Internally recorded as `record_time`. - **Date:** The date on which the continuous heart rate data was recorded. Internally recorded as `date`. - **Heart Rate Samples:** Collection of 5-minute average samples of heart rate during the measurement period. Samples may occasionally be recorded more frequently than every 5 minutes. The unit for heart rate samples is beats per minute (bpm). Internally recorded under `heart_rate_samples` with detailed properties: - **Heart Rate:** The heart rate recorded at a specific time, expressed in beats per minute. Internally recorded as `heart_rate`. - **Sample Time:** The specific time at which each heart rate measurement was taken, formatted to include hour, minute, and second. Internally recorded as `sample_time`. ### Polar SleepWise Circadian Bedtime Provides information about the circadian bedtime, which is the optimal time to go to bed for the best sleep quality. It is stored internally as `polar_sleepwise_circadian_bedtime` and includes the following fields: - **Record Time:** Considered `period_end_time`, stored as milliseconds since epoch. Internally recorded as `record_time`. - **Validity:** Indicates the validity of the circadian bedtime data. Internally recorded as `validity`. - **Quality:** The quality of the circadian bedtime data. Internally recorded as `quality`. - **Result Type:** The type of result or measurement being reported. Internally recorded as `result_type`. - **Period Start Time:** The start time of the circadian bedtime measurement period. Internally recorded as `period_start_time`. - **Period End Time:** The end time of the circadian bedtime measurement period. Internally recorded as `period_end_time`. - **Preferred Sleep Period Start Time:** Designated start time of the preferred sleep period for circadian alignment. Internally recorded as `preferred_sleep_period_start_time`. - **Preferred Sleep Period End Time:** Designated end time of the preferred sleep period for circadian alignment. Internally recorded as `preferred_sleep_period_end_time`. - **Sleep Gate Start Time:** Start time of the suggested sleep gate, which indicates the optimal window for falling asleep according to circadian rhythms. Internally recorded as `sleep_gate_start_time`. - **Sleep Gate End Time:** End time of the suggested sleep gate, indicating the closing of the optimal window for falling asleep. Internally recorded as `sleep_gate_end_time`. - **Sleep Timezone Offset Minutes:** The timezone offset in minutes from UTC for the sleep data, which helps in aligning the sleep data with local time accurately. Internally recorded as `sleep_timezone_offset_minutes`. ### Polar SleepWise Alertness Provides information about the user's alertness levels during sleep. It is stored internally as `polar_sleepwise_alertness` and includes the following fields: - **Record Time:** Considered `period_end_time`, stored as milliseconds since epoch. Internally recorded as `record_time`. - **Grade:** A numerical grade reflecting alertness level. Internally recorded as `grade`. - **Grade Validity Seconds:** Duration in seconds for which the alertness grade is considered valid. Internally recorded as `grade_validity_seconds`. - **Grade Type:** The type of grading system used for alertness evaluation. Internally recorded as `grade_type`. - **Grade Classification:** Classification of the grade based on alertness levels. Internally recorded as `grade_classification`. - **Validity:** Indicates whether the grade is currently valid. Internally recorded as `validity`. - **Sleep Inertia:** Description related to the user's state of sleep inertia. Internally recorded as `sleep_inertia`. - **Sleep Type:** Type of sleep during which the alertness data was recorded. Internally recorded as `sleep_type`. - **Result Type:** The type of result generated for alertness measurement. Internally recorded as `result_type`. - **Period Start Time:** The start time of the alertness measurement period. Internally recorded as `period_start_time`. - **Period End Time:** The end time of the alertness measurement period. Internally recorded as `period_end_time`. - **Sleep Period Start Time:** The start time of the sleep period associated with the alertness data. Internally recorded as `sleep_period_start_time`. - **Sleep Period End Time:** The end time of the sleep period associated with the alertness data. Internally recorded as `sleep_period_end_time`. - **Sleep Timezone Offset Minutes:** Timezone offset in minutes for the sleep period's local time. Internally recorded as `sleep_timezone_offset_minutes`. - **Hourly Data:** List of hourly data throughout the alertness period. Internally recorded under `hourly_data` with detailed properties: - **Validity:** Indicates the validity of each hourly data point. Internally recorded as `validity`. - **Alertness Level:** The level of alertness measured during the hour. Internally recorded as `alertness_level`. - **Start Time:** The start time of the hourly measurement. Internally recorded as `start_time`. - **End Time:** The end time of the hourly measurement. Internally recorded as `end_time`. ## Data Collection Behavior Whenever there is new Polar data, the Polar's server will send the new data to Avicenna. ## Adding Polar As a Data Source See [Accessing Data Sources](../../data-sources/README.md#accessing-data-sources). ## Monitoring Polar Data You can monitor and export Polar data [using Kibana](../../analysis/kibana-basics/#avicenna-kibana-integration). ## Polar Data Source in Participant App After a participant joins a study, they need to grant access to Avicenna to collect data. To do that, the participant needs to go to `Settings` on the Avicenna app and click on `My Studies`. Then they should choose the study that is collecting Polar data. On the study's page, clicking on the `Data Sources` will take them to the data sources page: ![Study's Data Sources page in the Avicenna app](/assets/polar-study-data-sources-page-avicenna-app.png) On this page, the participant will see all of the data sources that the study uses to collect data. Among these data sources, on the corner of the Polar data source(s), there is a `Grant Access` button: ![Granting access to Polar on the Data Sources page](/assets/polar-study-data-sources-page-grant-access.png) By clicking on the `Grant Access` button, the participant will be directed to the sign-in page of the Polar official website. Then, they can decide whether they want to share those data with Avicenna: ![Granting access to Polar data](/assets/polar-granting-access.png) After clicking on Grant, the participant will be redirected to the Data Sources page of the study in the Avicenna app, and they have successfully granted access to Avicenna to gather Polar data. The participants can stop sharing the data anytime by clicking on `Revoke Access` on the Data Sources page. ![Revoking access to Polar data](/assets/polar-revoking-access.png) # WHOOP Health metrics from [WHOOP wearables](https://www.whoop.com/) can offer detailed insights into individual performance, recovery, and sleep patterns, facilitating more precise health analyses and personalized care plans. This section explains how WHOOP integrates with Avicenna, making it easier for researchers to understand and use the performance-related data of their participants. ## Supported WHOOP Metrics in Avicenna In this section, we list the comprehensive range of WHOOP metrics that Avicenna supports. ### WHOOP Sleep Provides participant's sleep data. It is stored internally as `whoop_sleep` and includes the following fields: - **Sleep ID:** Unique identifier for the sleep record. Internally recorded as `event_id`. - **Start Time:** The start time of the sleep. Internally recorded as `start_time`. - **End Time:** The end time of the sleep. Internally recorded as `end_time`. - **Update Time:** The time this event was last updated in WHOOP. Internally recorded as `updated_at`. - **Timezone Offset:** The participant's timezone offset from UTC at the time the sleep was recorded. Internally recorded as `timezone_offset`. - **Nap:** Indicates if the sleep is a nap. Internally recorded as `is_nap`. - **Score State:** `SCORED` means the sleep activity was scored and the measurement values will be present (see the next field). `PENDING_SCORE` means WHOOP is currently evaluating the sleep activity. `UNSCORABLE` means this activity could not be scored for some reason, commonly because there is not enough participant metric data for the time range. Internally recorded as `score_state`. - **Score:** WHOOP's measurements and evaluation of the sleep activity. Only present if the Score State is `SCORED`. It is internally recorded as `score` and has the following fields: - **Stage Summary:** Summary of the sleep stages. It is internally recorded as `stage_summary` and includes: - **Total In-Bed Time:** Total time spent in bed, measured in milliseconds. Internally recorded as `total_in_bed_time_milli`. - **Total Awake Time:** Total time spent awake, measured in milliseconds. Internally recorded as `total_awake_time_milli`. - **Total No Data Time:** Total time with no data recorded, measured in milliseconds. Internally recorded as `total_no_data_time_milli`. - **Total Light Sleep Time:** Total time spent in light sleep, measured in milliseconds. Internally recorded as `total_light_sleep_time_milli`. - **Total Slow Wave Sleep Time:** Total time spent in slow wave sleep, measured in milliseconds. Internally recorded as `total_slow_wave_sleep_time_milli`. - **Total REM Sleep Time:** Total time spent in REM sleep, measured in milliseconds. Internally recorded as `total_rem_sleep_time_milli`. - **Sleep Cycle Count:** Number of sleep cycles. Internally recorded as `sleep_cycle_count`. - **Disturbance Count:** Number of disturbances during sleep. Internally recorded as `disturbance_count`. - **Sleep Needed:** Breakdown of the amount of sleep a participant needed before the sleep activity. Summing all individual components results in the amount. Internally recorded as `sleep_needed` and includes: - **Baseline Sleep Needed:** Baseline sleep needed, measured in milliseconds. Internally recorded as `baseline_milli`. - **Sleep Needed from Sleep Debt:** Sleep needed due to sleep debt, measured in milliseconds. Internally recorded as `need_from_sleep_debt_milli`. - **Sleep Needed from Recent Strain:** Sleep needed due to a recent strain, measured in milliseconds. Internally recorded as `need_from_recent_strain_milli`. - **Sleep Needed from Recent Nap:** Sleep needed due to a recent nap, measured in milliseconds. Internally recorded as `need_from_recent_nap_milli`. - **Respiratory Rate:** Respiratory rate in breaths per minute. Internally recorded as `respiratory_rate`. - **Sleep Performance Percentage:** Internally recorded as `sleep_performance_percentage`. - **Sleep Consistency Percentage:** Internally recorded as `sleep_consistency_percentage`. - **Sleep Efficiency Percentage:** Internally recorded as `sleep_efficiency_percentage`. ### WHOOP Workout Provides a participant's workout data. It is stored internally as `whoop_workout` and includes the following fields: - **Workout ID:** Unique identifier for the workout activity. Internally recorded as `event_id`. - **Updated At:** The time the workout activity was last updated in WHOOP. Internally recorded as `updated_at`. - **Start Time:** Start time bound of the workout. Internally recorded as `start_time`. - **End Time:** End time bound of the workout. Internally recorded as `end_time`. - **Timezone Offset:** The participant's timezone offset from UTC at the time the workout was recorded. Internally recorded as `timezone_offset`. - **Sport ID:** ID of the WHOOP Sport performed during the workout. Internally recorded as `sport_id`. You can check [WHOOP's reference document](https://developer.whoop.com/docs/developing/user-data/workout#whoop-sports) for possible values. - **Score State:** `SCORED` means the workout activity was scored and the measurement values will be present (see the next field). `PENDING_SCORE` means WHOOP is currently evaluating the workout activity. `UNSCORABLE` means this activity could not be scored for some reason, commonly because there is not enough participant metric data for the time range. Internally recorded as `score_state`. - **Score:** WHOOP's measurements and evaluation of the workout activity. Only present if the Score State is `SCORED`. It is internally recorded as `score` and has the following fields: - **Strain:** WHOOP metric of the cardiovascular load which is the level of strain the workout had on the participant's cardiovascular system based on the participant's heart rate. Strain is scored on a scale from 0 to 21. Internally recorded as `strain`. - **Average Heart Rate:** The participant's average heart rate (beats per minute) during the workout. Internally recorded as `average_heart_rate`. - **Max Heart Rate:** The participant's max heart rate (beats per minute) during the workout. Internally recorded as `max_heart_rate`. - **Kilojoules:** Kilojoules the participant expended during the workout. Internally recorded as `kilojoule`. - **Percent Recorded:** Percentage of heart rate data WHOOP received during the workout. Internally recorded as `percent_recorded`. - **Zone Duration:** Breakdown of time spent in each heart rate zone during the workout. It is internally recorded as `zone_duration` and includes: - **Zone Zero:** Time spent with a Heart Rate lower than Zone One [0-50%]. Internally recorded as `zone_zero_milli`. - **Zone One:** Time spent in Heart Rate Zone One [50-60%]. Internally recorded as `zone_one_milli`. - **Zone Two:** Time spent in Heart Rate Zone Two [60-70%]. Internally recorded as `zone_two_milli`. - **Zone Three:** Time spent in Heart Rate Zone Three [70-80%]. Internally recorded as `zone_three_milli`. - **Zone Four:** Time spent in Heart Rate Zone Four [80-90%]. Internally recorded as `zone_four_milli`. - **Zone Five:** Time spent in Heart Rate Zone Five [90-100%]. Internally recorded as `zone_five_milli`. - **Distance:** The distance the participant traveled during the workout. Only present if the distance data is sent to WHOOP. Internally recorded as `distance_meter`. - **Altitude Gain:** The altitude gained during the workout. This measurement does not account for downward travel; it is strictly a measure of altitude climbed. If a participant climbed up and down a 1,000-meter mountain, ending at the same altitude, this measurement would be 1,000 meters. Only present if altitude data is included as part of the workout. Internally recorded as `altitude_gain_meter`. - **Altitude Change:** The altitude difference between the start and end points of the workout. If a participant climbed up and down a mountain, ending at the same altitude, this measurement would be 0. Only present if altitude data is included as part of the workout. Internally recorded as `altitude_change_meter`. ### WHOOP Recovery Provides participant's recovery data. It is stored internally as `whoop_recovery` and includes the following fields: - **Cycle ID:** Unique identifier for the recovery cycle. Internally recorded as `event_id`. - **Sleep ID:** ID of the sleep associated with the recovery. If no sleep is associated with the recovery, defaults to -1. Internally recorded as `sleep_id`. - **Updated At:** The time the recovery was last updated in WHOOP. Internally recorded as `updated_at`. - **Score State:** `SCORED` means the recovery was scored and the measurement values will be present (see the next field). `PENDING_SCORE` means WHOOP is currently evaluating the cycle. `UNSCORABLE` means this cycle could not be scored for some reason, commonly because there is not enough participant metric data for the time range. Internally recorded as `score_state`. - **Score:** WHOOP's measurements and evaluation of the recovery. Only present if the Score State is `SCORED`. It is internally recorded as `score` and has the following fields: - **Recovery Score:** Percentage that reflects how well prepared the participant's body is to take on strain. The recovery score is a measure of the participant's body's "return to baseline" after a stressor. Internally recorded as `recovery_score`. - **Resting Heart Rate:** The participant's resting heart rate. Internally recorded as `resting_heart_rate`. - **HRV RMSSD:** The participant's Heart Rate Variability measured using the Root Mean Square of Successive Differences (RMSSD), in milliseconds. Internally recorded as `hrv_rmssd_milli`. - **SPO2 Percentage:** The percentage of oxygen in the participant's blood. Only present if the participant is on WHOOP 4.0 or greater. Internally recorded as `spo2_percentage`. - **Skin Temp Celsius:** The participant's skin temperature, in Celsius. Only present if the participant is on WHOOP 4.0 or greater. Internally recorded as `skin_temp_celsius`. - **User Calibrating:** Indicates if the participant is still calibrating and not enough data is available in WHOOP to provide an accurate recovery. Internally recorded as `user_calibrating`. ## Data Collection Behavior Whenever there is new WHOOP data, the WHOOP's server will send the new data to Avicenna. ## Adding WHOOP As a Data Source See [Accessing Data Sources](../../data-sources/README.md#accessing-data-sources). ## Monitoring WHOOP Data You can monitor and export WHOOP data [using Kibana](../../analysis/kibana-basics/#avicenna-kibana-integration). ## WHOOP Data Source in Participant App After a participant joins a study, they need to grant access to Avicenna to collect data. To do that, the participant needs to go to `Settings` on the Avicenna app and click on `My Studies`. Then they should choose the study that is collecting WHOOP data. On the study's page, clicking on the `Data Sources` will take them to the data sources page: ![Study's Data Sources page in the Avicenna app](/assets/whoop-study-data-sources-page-avicenna-app.png) On this page, the participant will see all of the data sources that the study uses to collect data. Among these data sources, on the corner of the WHOOP data source(s), there is a `Grant Access` button: ![Granting access to WHOOP on the Data Sources page](/assets/whoop-study-data-sources-page-grant-access.png) By clicking on the `Grant Access` button, the participant will be directed to the sign-in page of the WHOOP official website. Then, they can decide whether they want to share those data with Avicenna: ![Granting access to WHOOP data](/assets/whoop-granting-access.png) After clicking on Grant, the participant will be redirected to the Data Sources page of the study in the Avicenna app, and they have successfully granted access to Avicenna to gather WHOOP data. The participants can stop sharing the data anytime by clicking on `Revoke Access` on the Data Sources page. ![Revoking access to WHOOP data](/assets/whoop-revoking-access.png) # Activities Activities are the tasks that you require participants to perform during your study. Currently, we support 6 types of activities: - Surveys - Eligibility Surveys - Dropout Surveys - Cognitive Tasks - Stroops - Matrix Reasoning - Time Use - Working Memory Updating :::note You can only have one **Eligibility Survey** and one **Dropout Survey** in your study. ::: An activity, regardless of its type, contains a few core components. They include: - [**Triggering Logics**](triggering-logics.md): defines when the Activity should be prompted to the participants, and how it should be repeated. - [**Notification Templates**](../study-setup-and-deployment/notifications.md#notification-templates): defines how and when the participant should be notified (or reminded) about the Activity. - [**Criteria**](criteria.md): specifies under what conditions the Activity is enabled or disabled for a given participant. We describe each of these components, and other available attributes, in the following sections. ## Accessing Activities Through the **Activities** page on your Researcher Dashboard, you can see the list of activities for your study. Also, you can manage and modify your activities. ![Accessing the Activities Page in the Researcher Dashboard](/assets/activities-page.png) You can add a new Activity by clicking on the **Create New Activity** button. First, you must select an Activity type from the list. ![Creating A New Activity on the Activities page](/assets/new-activity.png) For example, after selecting **Survey**, you will be asked to choose whether you want to create a new Survey or import an existing [Survey Definition File](../terminology.md#survey-definition-file). ![Creating or Importing a Survey on the Activities page](/assets/create-import-survey.png) After finalizing this dialog, you will be taken to the Activity Editor page where you can modify your Activity. Each Activity that you add to your study is listed on the Activities page within a table where each column includes details about the Activity. Default columns include the following: - `Name`: The name assigned to this Activity by you. - `ID`: Each Activity in Avicenna is automatically assigned an ID unique across the whole system. This ID is shown here. - `Status`: This indicates whether an Activity is already _Published_, or is in _Draft_ (Only for Survey type Activities) mode. More on that [here](../surveys/README.md#publish-surveys). - `Triggering Logics`: When the Activity should be prompted to the participant. More on that [here](triggering-logics.md). - `Expiry Time`: Indicates how much time participants have to complete the activity. You can read more about Expiry Time [here](activity-sessions#expired-sessions-and-expiry-time). - `Notification Templates`: How the participant should be notified or reminded about the Activity. You can read more about Notification Templates [here](../study-setup-and-deployment/notifications.md#notification-templates). - `Description`: This is a description of your Activity. Via the three dots at the end of each row, you will also get the option to perform the following actions on a given Activity: - `Edit` opens the Activity in the relevant Activity Editor where you can modify it. - `Release` prompts the Activity to one or more participants right away. - `Duplicate` creates a copy of your Activity. - `Move` moves the Activity from the current study to another study. You need to have the required permissions on both studies. Also, the Activity shouldn't have any [session](activity-sessions.md) for any participant. :::note Survey question references (for example, question IDs used in criteria fields or question content placeholders) might need manual adjustment after you move the activity. ::: - `Go to Responses` (only for Survey type Activities) takes you to the _Survey Responses_ page where you can see the responses of the participants to that Survey. Discover additional details on the topic through [View Responses](../surveys/view-responses) - `Delete` deletes the Activity from your study. The data currently collected for this Activity will _not_ be removed. ![Activity-related Actions on the Activities page](/assets/activity-actions.png) :::note When you make any changes to a given study, such as adding, modifying, or deleting its Activities, moving them, or duplicating them, the change is not immediately received by the participants' devices. You need to update the device for all participants currently enrolled, as [described here](../study-setup-and-deployment/participation.md#reload-devices). Any participant who joins your study after this change will have the latest changes to the Activities. ::: ## Activity Editor Avicenna provides a graphical user interface that allows you to modify your Activity. The options you have in this editor depend on the type of your Activity. For example, the Survey Editor allows you to add different questions, while the Stroop Editor allows you to configure the cognitive task. The following screenshot shows the Survey Activity Editor: ![Survey Activity Editor UI](/assets/activity-editor-example.png) Each Activity Editor contains a few sections shown on the top and right sides of the page. What you see in the _Content_ page will be different depending on the Activity type. You can change the content of your Activity in this section. The next, _Triggering Logics_ allows you to define and configure Triggering Logics for your Activity. We explain Triggering Logics in-depth in the [Triggering Logics](triggering-logics.md) section. The third page, _Notification Templates_, allows you to configure the _Notification Templates_ for your Activity. You can learn more about them in the [Notification Templates](../study-setup-and-deployment/notifications.md#notification-templates). The last page on the Activity Editor, _Preview & Publish_, allows you to preview your Activity based on the settings you entered, and if everything is the same as you expect, publish it to your study. Finally, all activities have a **Settings** tab inside their editor. This tab includes general settings for the activity, such as its name, description, button icon, and caption. You can also find the Criteria and Expiry Time settings here. :::note The Criteria filed is only available for Survey activities. Also, Page activities do not have the Expiry Time field. ::: --- sidebar_position: 1 --- # Triggering Logics Triggering Logics, or _TL_ for short, for an Activity, specifies when the Activity should be prompted to the participant. Avicenna supports 5 types of Triggering Logics: - **User TL** specifies that the participant decides when and how often to start the Activity and respond to it. - **Time TL** specifies the Activity should be prompted based on a certain schedule. - **Proximity TL** specifies that data from [Bluetooth Beacons](../../reference/data-sources/from-smartphone/contact-network.md#bluetooth-beacons) determine when the Activity should be prompted. - **Public TL** allows anyone to answer your survey anonymously even without an account. You just need to share the link with them. - **Researcher-responded TL** enables researchers to initiate sessions for participants without granting them direct access. These sessions are conducted immediately, and researchers respond on behalf of the participants. Not all the Activities support all the different Triggering Logics. For example, while Survey Activities can have any of the above TLs, Matrix Reasoning or Time Use cannot be prompted via a Proximity TL. ## User TL A User Trigger Logic (TL) directs Avicenna to place a button on the study's homepage, labeled with the given caption. Each time the participant clicks this button, Avicenna creates a new session for the Activity. To set up a User TL, simply choose a caption and an icon for the button. You also have the option to define TL Criteria. ![Adding User Triggering Logics to the Activity](/assets/user-triggering-logic.png) The following image shows how an Activity with User TL is presented on the study homepage in the app: ![User Triggering Logics Presentation in the App](/assets/user-triggering-logic-in-app.png) As you can see in the image above, activities with User TL will appear under the _Optional Activities_ section. The title of this section can be changed to any name you want. To do this follow these steps: 1. Go to the _Basics_ page. 2. Scroll down to _Participant Triggered Activity_. 3. Set the title to the name you want for your user-triggered activities. :::info Avicenna won't send notifications to participants for activities started through User TL, unless you specifically ask us to do it for you. This is because the participant is already using the app. So, any automatic notifications for your activity won't go out if you start the session with User TL. ::: ## Time TL A Time TL specifies a schedule based on which the Activity is prompted to the participant. The following image shows the dialog for adding a new Time TL to your Activity: ![Time Triggering Logics for Activity](/assets/time-triggering-logic.png) In the setup dialog, you'll need to specify the timing for the first prompt, the frequency and pattern of any subsequent repetitions, and when these repetitions should end. Similar to other Triggering Logics, you can define a _Criteria_ for this process. Additionally, you have the option to choose a caption and an icon for the button that Avicenna displays on the participant's homepage for the prompted session. The first configuration for Time TL, _Time Format_, specifies whether you want to configure the schedule in _Absolute_ or _Relative_ terms. If you select the **Absolute** option, the time you specify will be set to a specific date and time, such as `2020-12-04 12:22:00`. With this setting, the Activity will be prompted exactly at this specified time. If you select the **Relative** option, you specify the time as duration. Avicenna then calculates the exact time for the Activity to be prompted by adding this duration to a base time. The base time can be either the participant's _Registration Date_ or _Time_. _Registration Time_ refers to the exact date and time when the participant joined your study. _Registration Date_ refers to the beginning of the date on which the participant joined your study. Following this, you specify whether you want to prompt the Activity at a time randomly chosen from a time window or at a certain time. If the former, enable the _Period_ option. If you select the _Period_ option, you'll be asked for a start and end time to pick a random time from. For the `Absolute` time format, you give specific start and end dates and times. With the `Relative` time format, you set start and end times relative to a `Base Time`. Avicenna adds these to the base time to find the period. Then, it uses either a _Uniform_ or _Normal_ distribution method to randomly choose a time within that period. When setting the **Base Time** to **Study Registration Date** in a Time Trigger Logic (TL), if a participant registers after the lower bound of the first trigger, no sessions will be generated for the day of their registration. In this scenario, session generation starts the next day after their registration. However, if a participant registers before the lower bound of the first trigger, they will receive a session on their registration day within the specified time frame of the trigger. After defining the time of the first prompt, you can decide whether your Time TL should be repeated or not. A Time TL can be repeated _Daily_, _Weekly_, _Monthly_, or _Yearly_. You also need to specify when the repetition should end. Let's go through setting up a Time TL for a clinical trial where we aim to assess how participants' mood and stress levels fluctuate at different times of the day. In this scenario, we want to prompt a survey every day at a random time between 8 am and 8 pm. We want to prompt the survey for 1 month after the participant joins the study. Here's how we set it up in Avicenna: - **Prerequisite** - _Activity Name:_ Daily Mood and Stress Assessment - _Type of Trigger:_ Time TL - _Time Format:_ Relative **Creating a Randomized Assessment Window:** - _Period Option_: Enabled - _First Trigger_: We define the first trigger as between `0 days at 08:00:00` and `0 days at 20:00:00`. This creates a 12-hour window within which assessments can occur. **Adjusting for Participant Entry:** - _Base Time:_ We check the Study Registration Date, so when the _First Trigger_ period is added to it, it always ends up being between 8 am and 8 pm. **Randomizing Assessment Times:** - _Distribution Function_: We choose the Uniform distribution to randomly select assessment times within the 12-hour window each day. - _Repetition_: We use Daily every 1 day, ensuring that participants receive their mood and stress assessment prompt at varying times each day. **Deciding When to Stop:** - _End Repetition:_ We choose `After 31 days at 00:00:00`. marking the conclusion of the daily assessments. The setup should be like the image below: ![Time Triggering Logics for Activity Example](/assets/time-triggering-logics-example.png) Through this setup, participants will receive random prompts for mood and stress assessments each day within a 12-hour window, offering insights into how their emotional states change during different times of the day. This method allows for a dynamic and comprehensive analysis of daily mood and stress patterns in the context of the clinical trial. ### Future Session Generation When a new participant joins your study, for each Time TL of each of your study's Activities, Avicenna creates the sessions they are expected to receive in the future. Therefore, you can see ahead of time when a given participant is prompted with which Activity. For longer studies, the number of sessions generated this way can be very large. To manage this load, Avicenna generates a limited number of sessions and generates more as needed, following the logic explained below. - When a participant joins your study, for each Time TL, Avicenna generates up to 50 sessions. - If the TL requires more sessions, Avicenna marks it as such. - Every time the number of sessions for such TLs drops below 25, Avicenna generates another 50 sessions. - The creation of new sessions occurs whenever the study is reloaded in the participant's app. This can be initiated by the researcher reloading the study on the participant's device, the participant pressing the 'Reload Studies' button in the app, or various other circumstances. For additional details, please refer to the [Audit Trail's Study Update Started](../study-setup-and-deployment/audit-trail.md#24-study-update-started). - If the study reload does not happen one week before the last scheduled session, Avicenna automatically reloads the study on the participant's device and generates more sessions for such TLs. ## Proximity TL Assuming your study is already configured to record participants' interactions with each other or with other physical objects using Bluetooth Beacons data source, the Proximity TL allows you to prompt a given Activity when proximity with certain attributes has started or has ended. Please refer to the [Bluetooth Beacon](../../reference/data-sources/from-smartphone/contact-network.md#bluetooth-beacons) page for the definition and details on some of the terminologies used below. The following image shows the dialog for adding a new Proximity TL to your Activity: ![Adding Proximity Triggering Logics to Your Activity](/assets/proximity-triggering-logic.png) The first few fields of this dialog are the same as other Triggering Logics: _Criteria_, _Button Caption_, and _Icon_. Further, in this dialog, you can specify what should be the **Team** and **Role ID** of the visiting beacon that is related to this Proximity TL. You can also specify whether the Activity should be prompted when the beacon of interest is visited, or after it's departed given a minimum contact duration. You also can specify how long apart should be two sessions from this Triggering Logics in the **Prompt Interval** field. The [Received Signal Strength Indicator](https://en.wikipedia.org/wiki/Received_signal_strength_indication) filter, or RSSI filter, allows you to specify how strong should be the signal of a visiting beacon to be considered for this Proximity TL. As the signal strength is commonly used as an indicator of the distance, you can use this option to specify how far the participant should be from the visiting beacon. ## Public TL Public TL allows for anonymous survey participation without requiring participants to have an account. ![Public Triggering Logic](/assets/triggering-logics-public.png) ### Session Management When you add a Public TL to your activity, the system generates a unique link for you that you can share with anyone to complete this activity. When the respondent opens the Public TL link, Avicenna initiates a new session for data collection. Participant responses for the current session are saved directly in the web browser. This means that if participants close or refresh their browsers, they can resume the session from the point where they stopped. However, if participants clear their browser's data, such as cookies and cached files, switch to a different web browser, or cancel the activity, clicking the link will result in a new session. Continuing from the previous discussion on session management, it's important to note the protocol for survey cancellation and submission. Participants have the option to cancel their participation at any point. If they choose to do so, they will be notified that their responses and any progress in the survey have been deleted. Additionally, upon the completion and submission of a survey, participants will receive a confirmation message acknowledging their submission. :::note Avicenna does not support notifications for anonymous participants. ::: ### Content of a Survey with Public TL When creating a survey with a Public TL, the survey's setup is similar to other surveys with one key difference: Criteria and placeholders cannot reference other surveys' sessions. However, they can reference the current session's questions. If you attempt to use criteria that reference another session, it will be evaluated as false. Similarly, using placeholders that reference other sessions will result in being replaced with an empty string. ### Participants Management Participants of a survey with Public TL will be all listed on the _Participation_ page under one log with an **Anonymous** ID. This means that regardless of the number of participants, there will be only one row with Anonymous ID. You can delete the data for all anonymous participants by clicking on the 3-dots menu at the end of the row and selecting _Delete_. ### Exporting Data Finally, for data export and analysis, you can export audit logs and survey responses for anonymous participants. Avicenna uses an _Anonymous ID_ for these participants. So the researcher can filter the data for anonymous participants by filtering it based on participants' IDs. Assuming you are familiar with [creating a filter](../study-setup-and-deployment/data-filtering.md), follow these steps on the Activity Responses page: 1. Choose `Participant` as the category. 2. Select `Avicenna ID` as the field. 3. Lastly, Click on `Anonymous` as the value. ![Filtering Anonymous Participants on Activity Responses page](/assets/teriggering-logics-filtering-anonymous-participants-activity-responses.png) You can do the same on the Audit Trial page following these steps: 1. Choose `Audit Trail` as the category. 2. Select `User ID` as the field. 3. Finally, Click on `Anonymous` as the value. ![Filtering Anonymous Participants on Audit Trial page](/assets/teriggering-logics-filtering-anonymous-participants-audit-trail.png) After applying the filter to display anonymous participant data, you can easily download this refined data by clicking the **Export as CSV** button next to the _Filter_ button. ## Researcher-responded TL The Researcher-responded TL allows researchers to schedule a new session for the _current date and time_, for a specific participant and respond to it on their behalf. This means that the participants won't have access to the responses and can't edit them, but the entered data will be linked to their participation record. This TL allows your study to implement _researcher-administered surveys_, or electronic case-report forms ([eCRF](https://en.wikipedia.org/wiki/Case_report_form)), along with ecological momentary assessments and interventions (EMA & EMI). For example, in a study measuring cognitive bias in patients with anxiety disorders, researchers might administer surveys at specific times following therapeutic interventions, directly by interviewing the participants, rather than asking the participants to complete the surveys themselves. The participants wouldn't directly interact with the activity; instead, researchers would observe behaviors or responses in a controlled setting and enter the data themselves. Note that even though participants do not provide answers to the questions in this case, their responses will still be considered as part of the criteria for a different question or activity. Further, note that you can not add a Researcher-responded TL to an Activity through the Activity Editor page. This TL is automatically assigned to the sessions that are generated and responded to by the researchers. Also, if a [Notification Template](../study-setup-and-deployment/notifications.md#notification-templates) is linked to an activity and the recipient of it is set to _Participants_, it will not send notifications to participants for sessions filled out by researchers. However, if the recipient of the notification template is set to researchers, the notification will be sent as planned. :::info Currently, only surveys out of all types of activities can be responded by researchers. ::: To submit a session as a researcher, follow these steps: 1. Go to the _Activity Sessions_ page. 2. Click on the `Submit New Session` button. ![Submit New Session](/assets/triggering-logics-researcher-responded-submit-new-session.png) 3. Select the participant and the activity you want to respond to. 4. Click on the `Next` button. Then you will be directed to a page containing the questions of the activity. You can now answer the questions as a researcher. ![Answering Questions as a Researcher](/assets/triggering-logics-researcher-responded-answering-questions.png) After you have answered the questions, you can [save](activity-sessions.md#saving-a-session) or [submit](activity-sessions.md#submitting-a-session) your session. You can also [edit your responses](activity-sessions.md#editing-responses) later. ## Geofencing TL Geofencing triggering logic allows activities to be triggered based on participants' presence relative to specific geographic boundaries. This triggering logic requires the [GPS data source](../../reference/data-sources/from-smartphone/location.mdx#gps) to be added to your study. ![Geofencing Triggering Logic Configuration](/assets/geofencing-triggering-logic.png) You can configure the following parameters for a Geofencing triggering logic: **Event Type**: It can be one of the following: - **Enter**: Triggers a session based on the time the participant enters the geofence. - **Stay**: Triggers a session based on the participant's continuous presence within the geofence for at least the amount specified in the "Minimum Duration" field. - **Exit**: Triggers a session based on the time the participant exits the geofence. **Minimum Duration**: Only available for the "Stay" event. The minimum amount of time the participant should be within the geofence for the "Stay" event to trigger a session. Defaults to 600 seconds. **Offset**: Delay the session trigger after the event. Defaults to 0 seconds. **Minimum Gap**: The minimum gap between two consecutive sessions of this TL. If the TL condition is met within this gap period, the new session won't be triggered. Operates only on the same triggering logic, so if you have multiple Geofencing TLs within your activity, multiple prompts within the specified minimum gap can occur. Defaults to 600 seconds. **Geofence Type**: It can be one of the following: - **Circular**: Defines the center coordinates and the radius (in meters). - **Polygonal**: Defines a polygon by specifying the coordinates of at least three vertices in the order they are connected. Each vertex should be unique, and the polygon must be simple, meaning it should not intersect itself. :::note All coordinates are expected in the [Geodetic decimal degrees format](https://en.wikipedia.org/wiki/Geodetic_coordinates). ::: :::info [This video](https://www.youtube.com/watch?v=LQz3kUMKMwU) might help you define your polygonal geofence using Google Maps. After downloading the KML/KMZ or CSV file, you can open the file using a text editor and extract the coordinates. ::: **Set Expiration Based on Exit Time**: Only available for "Enter" and "Stay" events. If enabled, the sessions created by this triggering logic will expire after the activity's `Expiry Time` has passed when the participant exits the geofence. In this case, a study-reload request will be sent to the participant's mobile apps so they get the calculated expiration time. On the other hand, if this option is disabled, the `Expiry Time` will be added to the scheduled time of the session ([which is the default behavior](./activity-sessions.md#expired-sessions-and-expiry-time)) to determine the calculated expiration time. **Trigger Session by Initial Location**: Only available for "Enter" and "Stay" events. If enabled, when the participant joins the study, their initial location will also be considered for "Enter" and "Stay" events. In such cases, for "Stay" events, the duration timer starts at the first location recording. :::info This triggering logic needs participants to be online and upload their GPS data to Avicenna regularly, if you want the triggering to be near real-time; sessions will be created on the server side and not the mobile apps. On the other hand, scheduling and expiring sessions will be done on the server based on the time GPS data is collected on the mobile app (`record_time` of the GPS records) and not the time such data is received by the server. ::: :::note After creating such sessions, the server will send the sessions to the participant's mobile apps. ::: ## Manually Triggering an Activity While you can use Triggering Logics to specify when or how Avicenna should allow the participant to complete an Activity, there might be times that you want to prompt the Activity right away to one or more participants. Avicenna allows you to manually trigger an Activity. In this case, Avicenna will ignore the Activity and TL [Criteria](criteria.md) (if any) and prompt the Activity to the participant right away. To trigger an activity manually: - Go to the `Activity Sessions` page. - Click on the `Create New Sessions`. - Select the `Release Activity` option. - In the release activity dialog, choose the specific activity you wish to manually trigger. - Select the participants who should receive this activity. - Finally, click on the `Release` This will prompt the chosen activity to the selected participants. | ![Create New Session](/assets/triggering-logics-create-new-sessions.png) | ![Release Activity Dialog](/assets/triggering-logics-release-activity-dialog.png) | | :----------------------------------------------------------------------: | :-------------------------------------------------------------------------------: | | Create New Session | Release Activity Dialog | The above steps result in a notification on the participant's phone to let them know they have an Activity to complete. ## How-Tos - [Create a Baseline Survey](../../how-to/activities/how-to-create-a-baseline-survey-in-avicenna.md) - [Create a One Time Optional Survey](../../how-to/activities/how-to-create-a-one-time-optional-survey.md) - [Create Personalized Surveys](../../how-to/activities/personalized-surveys-in-avicenna.md) - [Prompt a Survey More Than Once a Day](../../how-to/activities/prompt-a-survey-more-than-once-a-day.md) - [Enable Triggering Logic Only for One Participant](../../how-to/activities/enable-triggering-logic-only-for-one-participant.md) ## Best Practices - [When to prompt surveys to maximize the responses?](https://avicennaresearch.com/blog/when-to-prompt-surveys-to-maximize-the-responses/) --- sidebar_position: 2 --- # Criteria Criteria in Avicenna is a [conditional expression](https://en.wikipedia.org/wiki/Conditional_%28computer_programming%29), or a formula, that instructs Avicenna whether an action has to happen (or a study section should be shown/activated) with respect to the context of the participants, which eventually increases the compliance rate of participants. Avicenna allows adding a criteria to the following elements: - [Eligibility Surveys](../study-setup-and-deployment/eligibility-screening.md) - [Activities](./README.md) - [Triggering Logics](triggering-logics.md) - [Survey Sections](../surveys/flow-control.md#showing-or-skipping-a-section-or-question-using-criteria) - [Survey Questions](../surveys/flow-control.md#showing-or-skipping-a-section-or-question-using-criteria) - [Notification Templates](../study-setup-and-deployment/notifications.md#notification-templates) 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: ```text 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: ```text 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: ```text (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: | 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 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](./README.md) and the [question ID](../surveys/view-responses.md#response-metadata) 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](/assets/criteria-typing-mode.png) | | :---------------------------------------------------------------------: | | 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](/assets/criteria-interactive-mode.png) | | :-------------------------------------------------------------------------------: | | 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](mailto:support@avicenna.com). --- sidebar_position: 3 --- # Activity Sessions When an Activity is prompted to a participant, Avicenna will create a [Session](../terminology.md#session) for it. This session will hold information about the prompted Activity, responses provided by the participant or the researchers so far, and other related metadata. To get an overview of the sessions in your study, follow these steps: - Open the `Activity Sessions` page on the Researcher Dashboard. - Go to the `Participants` tab from the right-side panel and select the participants whose sessions you want to check. Note that currently, you can choose a maximum of 5 participants. - Then go to the `Activities` tab and select your desired Activities. - Press `Apply Filters`. ![Activity Sessions page](/assets/activity-sessions-page.png) Following this, you can access all the Activity sessions with their status for the selected participants. You can view the Activity sessions starting when a particular participant joins your study. To do this, after selecting a Participant ID under the `Participants` tab, click on the `Go to Join Time` button that appears. This is an important feature because it allows you to check all your study sessions and ensure they are created correctly for all the participants. As you see in the top left corner, you can also specify the period that you want the sessions to be displayed in. You can select a Daily, Weekly, Monthly, or Yearly view. Also, below the session statuses, you can find a progress bar. As you hover the mouse over it, a tooltip appears that shows the number and percentage of sessions with a particular status. The image below shows that we have 245 _Unanswered_ sessions for the selected participants, accounting for more than 82% of the sessions. Also, you can hide or show sessions with specific statuses by tapping their status badge above the calendar. ![The progress bar on the Activity Sessions page](/assets/activity-sessions-progress-bar.png) ## Session Statuses Each session has a status that can be one of the following: - **Unanswered/Unknown (ID 0)** indicates that a response to this particular session hasn't been registered or uploaded yet. This status doesn't necessarily mean the session hasn't been initiated; it might have been prompted, but the response is yet to be recorded. - **Completed (ID 1)** indicates the participant completed the session and submitted it. - **Canceled (ID 2)** indicates the participant did not want to complete the session and explicitly canceled it. - **Expired (ID 3)** indicates the session was not responded to in time, so Avicenna automatically marked the session as expired. - **Blocked (ID 4)** indicates the session was blocked by another active session from the same Activity and could not be prompted (more details below). - **In Progress (ID 6)** indicates the session is started by the participant but it's not completed, canceled, or expired yet. In Avicenna, we consider an activity session a "concluded" when its status is one of the following: - Completed - Expired - Canceled - Blocked For _Expired_, any data collected up to the time of expiration will be uploaded to Avicenna servers. Also, _Blocked_ sessions indicate the Activity was not prompted to the participant, and therefore, there is no response available for it. ### Expired Sessions and Expiry Time Each Activity can have an _Expiry Time_, which specifies how long after the _Scheduled Time_ Avicenna should wait for the participant to complete the Activity and submit it. If a participant fails to submit their response within the set timeframe, the session will be labeled as Expired. ### Blocked Sessions Each Activity can only have one session running at a time; sessions cannot overlap. If a new session is triggered while another session is already running for the same Activity, the new session will immediately be closed and labeled as 'Blocked'. Let's say you schedule an Activity with a Time Trigger Logic (TL) for 8 am and 9 am, with expiry time set to 2 hours. At 8 am, Avicenna prompts the participant, starting a new session and waiting for completion. If by 9 am the participant hasn't responded or canceled the first session, the 9 am session can't start because the 8 am session is still active. Avicenna will then mark the 9 am session as 'Blocked'." :::info Bear in mind that once a session is canceled, expired, blocked, or completed, the corresponding upcoming [Session Release Notifications](../study-setup-and-deployment/notifications.md#notification-templates) will not be sent. ::: ## Sessions Metadata Clicking on each session will give you its metadata which includes _Activity_, _Participant_, _Scheduled Time_, _Response Time_, and _UUID_. - **UUID** is a Universal Unique Identifier that uniquely identifies a session in Avicenna. - **Scheduled Time** specifies the time that the Activity was scheduled to be prompted. For sessions that are prompted via Triggering Logics types other than Time TL, this is set to the time the Avicenna app starts the session. - **Response Time** specifies the time the Activity session was concluded and queued to be uploaded to the Avicenna server. :::info Whether you use Avicenna as a researcher or participant, all time values are automatically converted to your local time zone, i.e., Avicenna displays all the sessions based on the user's local time zone. Please refer to the [Participation Period](../study-setup-and-deployment/participation-period.md) to learn how Avicenna deals with time. ::: ![Session metadata](/assets/activity-sessions-session-metadata.png) Let’s work on an example scenario here. Assume that you are interested in viewing all the sessions that were or will be prompted for one of your study's participants (ID: 59982) in March 2023. To see these Activity sessions, - Choose the `Participants` and the `Activities` from the right-side panel. - Press `Apply Filters`. - Then set the view to `Month` and select **March 2023** for the date range. Now you can see all the sessions scheduled for this participant in March 2023 with their status. Note that if there are more than two sessions in a cell, you will see a `More` button, which, if clicked on, will show you the list of all sessions in that particular time slot cell. ![Viewing the sessions on the Activity Sessions page](/assets/activity-sessions-viewing-sessions.png) ## Actions on the Activity Sessions You can perform several actions on a session on the `Activity Sessions` page, including _creating_, _editing_, and _deleting_ sessions. You can also _edit the responses_ to a session as a researcher. ### Creating a Session The `Activity Sessions` page offers you two ways to create a session, and after creating such sessions, the mobile devices for the corresponding participants will get reloaded automatically. #### Using a CSV File You can tap the `Create New Sessions` button above the calendar and select `Create via CSV File` to upload a CSV file. The CSV file must include the Participant ID, the Activity ID, and the Scheduled Time in each row. For instance, the CSV file can be like this: ```csv user_id,activity_id,scheduled_time 44457,14269,1705814200000 44658,14369,1706821400000 ``` If you still need a sample file to modify and use, you can download it by clicking on the link inside the dialog you can see below: ![Creating Sessions using a CSV file](/assets/activity-sessions-create-sessions-using-csv-file.png) In this interface, you have the option to either drag and drop your file or choose it directly from your device. Upon confirmation, a dialog will appear displaying which sessions were successfully created and identifying any that encountered issues: ![Create Sessions via CSV File Results](/assets/activity-sessions-create-sessions-using-csv-file-result.png) :::info The Scheduled Time should be in milliseconds since the Unix epoch. You can use a tool like [Epoch Converter](https://www.epochconverter.com/) to convert the date and time to milliseconds. ::: #### Using the Calendar Another way is that you can also click on the whitespace area of the calendar cells for the upcoming days. This will take you to the `Create Session` dialog, where you can specify the **Activity**, the **Participant**, the **Scheduled Time**, and the **Expiry Time**. Note that the session that you create this way or using a CSV file will be a [Researcher-Defined Session](../terminology.md#researcher-defined-session). ![Creating a Researcher-Defined Session](/assets/activity-sessions-create-researcher-defined-session.png) :::info When you create a session in the Create Session dialog, only the selected participants from the right-side panel will be visible in the Participant field. Also, you can create sessions for one participant at a time. However, using the CSV option, you can create multiple sessions for multiple participants and activities. ::: ### Releasing an Activity There might be times that you want to prompt the Activity right away to one or more participants. Avicenna allows you to manually trigger an Activity. To read more about this, check the [Manually Triggering an Activity](./triggering-logics.md#manually-triggering-an-activity) section. ### Deleting a Session If you want to delete a session, there are two ways: 1. First, tap the `Delete Sessions` button above the calendar and enter the UUID of the sessions you want to delete. As you see in the image below, you can only delete the Researcher-Defined sessions here. Also, note that only future sessions can be deleted. ![Deleting Researcher-Defined Sessions](/assets/activity-sessions-delete-researcher-defined-session.png) 2. Second, click on any session (in the future or the past) in the calendar and tap the `Delete` icon. Doing this opens a dialog where you must confirm that you want to delete the session. Note that here you can delete all the possible session types, including Time TL and Researcher-Defined sessions. Avicenna will automatically reload the devices for such sessions. ![Session deletion confirmation dialog](/assets/activity-sessions-delete-confirmation-dialog.png) ### Editing a Session In addition to creating or deleting, you can edit a session on the Sessions page. Keep in mind that _you can only edit future sessions_. To do this, - Click on an upcoming session in the calendar. - Then tap the `Edit` icon. - You can change the **Scheduled Time** and **Expiry Time** in the opened dialog. - By default, the participant’s device will be reloaded to ensure the changes are applied. Note that, like deleting a session, you won’t see the _Reload participant’s device_ option for the Researcher-Defined sessions, as Avicenna will automatically update them. :::note The `Edit Session` option is disabled for [Researcher-responded sessions](triggering-logics.md#researcher-responded-tl) due to the immediate scheduling nature of these sessions. As they are set to occur 'now,' effectively the moment they are created, their scheduled time is immediately considered to have passed. Consequently, no changes can be made to the session once it has begun. ::: ### Editing Responses > Available for surveys only, excluding > [Eligibility](../study-setup-and-deployment/eligibility-screening.md#eligibility-survey) and > [Dropout](../study-setup-and-deployment/study-dropout.md#dropout-survey) surveys As a researcher, you may need to edit the responses of the participants. Avicenna allows you to edit the responses of the participants for a session. To do this, follow these steps: - Go to the _Activity Sessions_ page. - Click on the session you want to edit. - Click on the `Edit Response` button, and you will be directed to the page where you can edit the responses. ![Edit Response](/assets/activity-sessions-edit-response.png) Some types of questions allow you to clear the current answer by clicking on the clear button rather than doing it manually. These question types include: - [Single Answer](../surveys/questions.md#single-answer) - [Visual Analog Scale (VAS)](../surveys/questions.md#visual-analog-scale-vas) - [Calendar](../surveys/questions.md#calendar) - [Audio](../surveys/questions.md#audio) - [Video](../surveys/questions.md#video) - [Image](../surveys/questions.md#image) - [Audio/Text](../surveys/questions.md#audio-text) For surveys, you can also view the response history for each of the questions by clicking on the 3-dots menu and clicking on `View Response History`. To learn more, check the [Viewing Survey Response History](../surveys/view-responses.md#viewing-survey-response-history) section. Also, you can view the comments on any response or add your own. To do this, click on the 3-dots menu and then click on `View Response Comments`. To learn more, check the [Commenting on Survey Responses](../surveys/view-responses.md#commenting-on-survey-responses) section. :::info Editing the sessions other than the [Researcher-responded sessions](../activities/triggering-logics.md#researcher-responded-tl) will result in reloading the participants' devices. However, if editing a Researcher-responded session results in a change of criteria or survey question content placeholders of another session, the participants' devices will be reloaded. ::: :::note When you're editing the responses as a researcher, the session won't expire even if the survey has an [expiry time](#expired-sessions-and-expiry-time). ::: #### Saving a Session After you have modified the answers, you can `Save` or `Submit` the session by clicking on the button at the top right corner of the page. If you click on `Save`, the session will be saved and the session's status will be changed to _In Progress_. If the response to a question is invalid based on the question properties (e.g. format, min, max), you won't be able to save your response and you will be informed by an alert message. #### Submitting a Session If you click on `Submit`, the session will be saved and the session's status will be changed to _Completed_. However, the _Response Time_ for the session will be set only the first time you submit your answer. Same as saving a session, you can't submit your response if your responses are invalid based on the question properties. ## Downloading Sessions The `Activity Sessions` page also lets you download all the sessions defined in your study in a CSV format. To do that, tap the `Download as CSV` button above the calendar. The downloaded file provides information about the sessions, including the Participant ID, the Activity ID, the Scheduled Time, the Record Time, Status, etc. ## Troubleshooting ### One or more sessions are missing If you notice that some sessions are missing from the `Activity Sessions` page or the downloaded CSV file, you can follow these steps to diagnose and fix the issue: 1. Check [the general steps to diagnose participation issues](../study-setup-and-deployment/participation.md#general-steps-to-diagnose-participation-issues). 2. Check [the corresponding triggering logic](triggering-logics.md) of the activity to see if it's there and if yes, its configurations are as you expect. 3. Check if the expected scheduled time is within [the participation period](../study-setup-and-deployment/participation.md#participation-tab) of the corresponding participant. 4. Check if the the corresponding activity's or triggering logic's [criteria](criteria.md), if any, was False for the corresponding participant at the time the session was supposed to be scheduled for. 5. Check if the session is manually deleted (either by a researcher or the system somehow). You can do this by finding [the "TUD Session Rescheduled or Deleted"](../study-setup-and-deployment/audit-trail.md#124-tud-session-rescheduled-or-deleted), ["TUD Session Deleted"](../study-setup-and-deployment/audit-trail.md#125-tud-session-deleted), and ["Time Session Rescheduled or Deleted"](../study-setup-and-deployment/audit-trail.md#126-time-session-rescheduled-or-deleted) audit logs for the corresponding participant. 6. If the session was supposed to be created by the participant (e.g., based on a User triggering logic), check if the participant was online and synced their sessions and responses with the server since then. You can do this by finding [any audit log for the corresponding participant](../study-setup-and-deployment/audit-trail.md#user-id). # Surveys A Survey is a type of [Activity](../activities/) you can add to your study in Avicenna and is arguably the most common Activity participants do in a research study. Surveys share all features of Avicenna Activities, as we described previously, such as [Triggering Logics](../activities/triggering-logics.md), [Notification Templates](../study-setup-and-deployment/notifications.md#notification-templates), and [Criteria](../activities/criteria.md). If you have not reviewed these features already, we suggest you read about them first. In this section, we focus on features that are specific to the Surveys. ## Survey Structure Each Survey consists of one or more sections, and each section also contains one or more questions. Sections are used to group different questions, either because they are conceptually relevant or to apply branching or loop iterations to them. Questions are the main building blocks of a Survey that is presented to the participant to enter their responses. The Avicenna app shows questions one by one to the participant. Participants will not see any notion of sections within your Survey while responding to it. Surveys in Avicenna are defined using a [Survey Definition File](../terminology.md#survey-definition-file) which is basically a plain-text [JSON document](https://en.wikipedia.org/wiki/JSON). The file describes when the Survey should be prompted (the [_Triggering Logics_](../activities/triggering-logics.md)), how the participant should be notified (the [_Notification Templates_](../study-setup-and-deployment/notifications.md#notification-templates)), what enables or disables a Survey (the [_Criteria_](../activities/criteria.md)), what sections exist in the Survey, what questions each section contains, what is the branching and skip patterns, and any other settings Avicenna supports for Surveys. All these settings are defined in a schema file called [Avicenna Survey Schema](https://avicennaresearch.com/media/survey_content/survey_schema.json). When you create a Survey Activity, you can either use Avicenna Research's Survey Editor or Survey Definition File and upload it as your Survey. If you create and upload a Survey Definition File, Avicenna first validates it against the Survey Schema to make sure all settings are entered correctly. ### Versions, Import and Export To create a Survey from your Survey Definition File, you can upload the file to the Avicenna website. To import your Survey: 1. Open Avicenna Researcher Dashboard and navigate to the _Activities_ page. 2. Click on `Create New Activity`. 3. Select the `Survey` and then `Import a definition file`. ![Import dialog in the Activities page](/assets/survey-import-json.png) 4. Drop your Survey Definition File into the drop zone or choose your Survey Definition File from a directory on your computer. This will start validating the Survey Definition File. 5. Click on `Import` to create your Survey using this file. 6. If the file is not valid, you will see an error. You can refer to [JSON Content Validation](#survey-definition-file-validation) for details on how to validate your Survey Definition File. You can also import a Survey Definition File into your existing Survey. To do so: 1. Open the Survey Activity Editor for your desired Survey. 2. Go to `Preview & Publish`, then `Versions`. 3. There you will see the list of versions for your current Survey. 4. On top of the versions, click on `Upload Survey Definition File`. ![List of Survey Versions in the Survey Editor Preview & Publish section](/assets/survey-preview-publish-versions-tab.png) 5. You will see a similar _Import_ dialog as above. You can upload a valid Survey Definition File there. 6. When completed, the content of the file will be loaded into your Survey as a draft. You can preview and then publish this Survey. Every time you change your published Survey, a new (draft) version is created in Avicenna. You can see the list of all versions in the `Versions` tab, along with other information such as when the Survey was published, who published it, and what was noted left on that published version. For each version, you can click on `Download Survey Definition File` to download the content of that version as a Survey Definition File. You also can click on `Load this version` to load the selected published version of the Survey. This will create a new version of your Survey with the content of the version you selected and set it in draft mode. This option is not available for the last published version. On the other hand, for the draft version, if any, you'll find a `Discard` button. You can use that button to **discard your draft changes**. ### Survey Definition File Validation Avicenna does not offer an advanced [Survey Definition File](../terminology.md#survey-definition-file) validation. So if you try to upload a Survey Definition File that is invalid, you will just see an error saying the file is not valid, but no more details on what the issue is in the file. To get more information on exactly what the problem is with the file, you can use external JSON schema validators such as [this option](https://www.jsonschemavalidator.net/). On this website, you can upload the content of the Avicenna Survey Schema on the left side and the content of your Survey Definition File on the right side. This will validate the content of the Survey and show you any problems or errors: ![Validate Survey Definition File content using JSON validation tools](/assets/survey-validate-json.png) ## Preview Survey Before publishing your Survey, it's important to check it thoroughly to make sure there are no issues. The _Preview_ tab on the _Preview & Publish_ page can help you with this. The following image shows what this tab looks like: ![Preview tab in Preview & Publish page](/assets/survey-preview-publish-preview-tab.png) There are two sections on this page. The right side of the page shows a preview of the Survey. This preview can simulate exactly how the Survey flow will be in the Avicenna mobile or web app. From the top of the simulator, you can choose to preview a _Desktop_ or _Mobile_ view. This way, you can see how your Survey will look on different screen sizes. The left side of the page shows the list of Criteria from other Surveys that impact the flow of this Survey. As we explained in the [Criteria](../activities/criteria.md) section, in Avicenna, you can define a Criteria for a section or a question based on the responses to questions from other Surveys in your study. The _Preview_ tab detects such dependencies and loads those questions here on the left side. This allows you to try out the flow of the Survey using different assumptions. For example, consider the previous image. Assume the Survey asks about the weight and height of the participants, and if they are females between 18 to 40 years old, it also asks if they are pregnant. So the flow of the Survey depends on the gender and the age of the participant, which is asked in another Survey. That is why on the left side, you can see Avicenna lists two questions, one is asking the participant's gender, and the next one asks the participant's age: ![Criteria Questions in the Preview tab](/assets/survey-preview-publish-preview-criteria-questions.png) By default, these two questions have no answers. So the flow of the Survey behaves as if the participant skipped responding to these questions. If you answer these questions, Avicenna asks you to reload the Survey to see the changes in the Survey flow. You can click on the dialog or click on the `Reload` button in the top right corner to apply this change: ![Preview Reload in the Preview tab](/assets/survey-preview-publish-preview-reload.png) ## Publish Surveys Any changes you make to the Survey will be saved in the _Draft_ mode. This means while the changes are saved, they are not accessible to the participants (both test participants and real participants), and you may revert them if they are not satisfactory. To make them available to the participants, you need to publish your changes. You can publish your Survey using the _Publish_ tab of the Survey Editor's Preview & Publish page: ![Publish tab in Preview & Publish page](/assets/survey-preview-publish-publish-tab.png) This section first runs validation on your Survey to ensure all settings are done correctly. If there are any errors or warnings, you can see them under the _Activity Validation_ part. You must resolve all errors before you can proceed with publishing your Survey. When all issues in your Survey are resolved, or if there are no warnings or errors, you can press the `Publish` button to publish your Survey. You can also leave a note on this to document what changes were made as part of this published version. This note will be available later on in the _Versions_ tab. ## Export Your Survey as a PDF Avicenna allows you to export your Surveys in PDF format. Here is how you can do this: 1. In your Survey Editor, go to the _Preview & Publish_ page. 2. If you have already published your Survey, go to the _Versions_ tab. If not, you need to [publish your Survey](#publish-surveys) first. 3. On this page, you can see the list of your Survey versions. They are sorted based on the Version number. To export a copy of your Survey in PDF, select the _Download as PDF_ button from the version that you want. ![The _Download as PDF_ on the Preview & Publish page](/assets/survey-preview-publish-versions-download-as-pdf.png) ## Additional Settings Each Survey offers a set of additional settings. You can access these settings by opening the _Survey Editor_, navigating to the _Content_ page, and opening the `Settings` tab in the lower right corner. Below we describe each of these configurations. ### Criteria This specifies the criteria for the Survey Activity. This acts as the main Criteria for the Activity and supersedes the Criteria set on the Triggering Logics. You can learn more about Activity and Triggering Logics Criteria in the [Criteria Section](../activities/criteria.md). ### Section Randomization You can randomize the selection of the sections within your Survey using the options available in `Section Randomization`. This feature allows you to choose a subset of sections within your Survey using the `Included Section ID(s)` option and also choose a `Selection Count`. Using this, besides the sections that are not part of the `Included Section ID(s)`, only a subset of the specified sections will be used to construct the Survey, where the size of the subset is the same as the `Selection Count`. For example, assume the Survey has seven sections, and the `Included Section ID(s)` option is set to sections 3, 4, and 5, with a `Selection Count` of 2. With these settings, sections 1, 2, 6, and 7 will always be in the Survey, and from sections 3, 4, and 5, only two randomly selected sections will be used to construct the Survey. For example, the sections shown to the participant can be any of the following: - 1, 2, 3, 5, 6, 7 - 1, 2, 4, 5, 6, 7 - 1, 2, 3, 4, 6, 7 Similarly, you can enable the `Random Section Order` option. Doing so will randomize the order of _all_ sections of the Survey. Please note that these randomizations happen only once for each [Survey Session](../activities/activity-sessions.md) whenever the corresponding Survey is opened. ### Capture Location This option instructs Avicenna to capture the participant's location while answering a given Survey. When enabled, each response will be geo-tagged before storage. Note that this option is different from using the [Location Data Source](../../reference/data-sources/from-smartphone/location.mdx) in your study. When you add a Location Data Source to your study, the Avicenna app will continuously capture participants' location, whether they are answering a Survey or not. Such data is stored separately from the Survey responses. While it is possible to join the data at a later stage to infer the participant's location at the time of answering a Survey, this is not done automatically by Avicenna. On the other hand, the `Capture Location` option makes sure all Survey responses are geo-tagged, whether the Location Data Source is enabled or not, assuming the participant grants GPS permission to the Avicenna app and the GPS functionality is available and enabled on their phone. By default, this option is turned off. ### Show Progress This option provides a visual indicator showing how much of the survey is left to complete in the current session. The following picture shows the same Survey, with and without the `Show Progress` option enabled: | | | | :------------------------------------------------------------------------: | :------------------------------------------------------------------------------------: | | ![Avicenna Survey with Progress Display](/assets/survey-show-progress.png) | ![Avicenna Survey without Progress Display](/assets/survey-show-progress-disabled.png) | | Show Progress Enabled | Show Progress Disabled | Note that the progress shown here is approximate and does not present the exact number of questions left to complete. Certain sections or questions might not be presented due to the defined branching, skip patterns, or randomized section selection. In this case, the participant will notice a jump in progress. By default, this option is turned on. ### Show Previous Button This setting instructs Avicenna to show or hide the `Previous` button in a given survey. The `Previous` button allows participants to go back to the previous question(s) and change their response(s). By default, this setting is enabled. The following pictures show the same survey, with the `Show Previous Button` option enabled and disabled: | | | | :--------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------: | | ![Avicenna Survey with Previous Button](/assets/survey-show-previous-button-enabled.png) | ![Avicenna Survey without Previous Button](/assets/survey-show-previous-button-disabled.png) | | `Show Previous Button` Enabled | `Show Previous Button` Disabled | --- sidebar_position: 1 --- # Questions ## Common Question Attributes Avicenna supports 14 question types. Each question, regardless of its type, has the following attributes: ### Question ID Each question is automatically assigned a numerical ID unique within the Survey. This ID is used to uniquely identify the question or reference it when writing [Criteria](../activities/criteria.md). It is not related to the order of the questions within the Survey. ### Question Type The type of question is a property of the question which you can change. This enables you to quickly change the type of a question, for example, from _Single Answer_ to _Multiple Answer_ or from _Audio_ to _Audio/Text_. ### Variable Name When a participant answers a question, their input is typically stored as a value in a variable. The name of this variable can be modified according to your needs. For example, if the question is asking for the participant's age, the variable name could be set to "age" by you. ### Criteria The Criteria field is an essential component of a dynamic Survey, as it allows you to set specific conditions or rules that determine whether a particular question should be displayed to the participant or not. For more information on how to use Criteria on Survey questions in Avicenna, check [Flow Control](flow-control.md) ### Question Content The content of the question is to be shown to the participant. This content supports a limited set of [HTML tags](#adjusting-question-content) and may contain zero or more [videos or images](questions.md#multimedia). You can also use [placeholders](questions.md#placeholders) in your content which will be replaced by their value before Avicenna shows the content to the participant. ### Mandatory This determines whether the response to a particular question is mandatory or not. Participants have to provide an answer to the mandatory question before they can continue to the next question. If the question is marked as optional, participants can skip answering the question. ### Enabled This field lets you choose whether the question is, by default, enabled or disabled. If a question is disabled, it will not be presented to the participant, and the participant can continue the Survey without answering the question, even if it's mandatory. The _Enabled_ status of a question can be linked to a potential answer in a given Single Answer or Multiple Answer question. This way, if the designated answer is selected by the participant, the question will be enabled; otherwise, it will be disabled. You can read more about this in the [Enabling/Disabling Questions](flow-control.md) section. ### Answers Properties Each Multiple Answer or Single Answer question contains a list of possible answers, which will be presented to the participant. Each of these answers, in turn, has certain properties that define if and how selecting that given answer should modify the Survey flow. The following image shows a Multiple Answer question with five answers, and you can see the properties of the first answer marked in the Properties tab: ![Answers Properties of Multiple Answer Question](/assets/survey-questions-type-multiple-answer-answers-properties.png) #### Answer Type Answers can be as text or as an image. If you prefer to use an image for a given answer to a _Multiple Answer_ or _Single Answer_ question, you simply can switch to the _Image_ option and then upload the desired image instead of typing the text for that answer. As you can see in the Answer Properties tab, in addition to an ID and type, each answer has other properties as follows: #### Enable Questions This property allows you to define a list of questions that should get enabled or disabled based on whether this answer is selected or not, respectively (as described [here](flow-control.md#showing-or-skipping-a-question-using-the-enable-questions-option)). #### Next Section ID This specifies the section which should be shown following the current section, given this answer is selected. The available options are: - **No Change**: Selecting or deselecting this answer should not change the current order of the sections. Therefore this answer has no impact on the Survey flow. This is the default option. - **Finish the Survey**: Selecting this answer will mark this section as the last section and will finish the Survey. - **Section Number**: Selecting a given section number will instruct Avicenna to continue from the section specified here. You can read more about this option in the [Flow Control](flow-control.md) section. ## Question Types ### Information You can use Information questions to show blocks of text, images, or videos to participants. The content shown for this question, similar to the content of any other question type, supports basic HTML tags. You can format the text into paragraphs, style the text by using bold or italics, or add hyperlinks. The following image shows how the Information question is presented in the Avicenna app: ![Information Question in an Avicenna Survey](/assets/survey-questions-type-information-sample.png) ### Multiple Answer Multiple Answer questions provide participants with one or more potential choices from which they can choose zero or more as their response. Note that if a _Multiple Answer_ question is set to mandatory, participants have to choose at least one answer. Therefore, it's important to ensure provided choices cover all possible cases the participant may want to choose, including choices such as `None of the above`. In addition to the common attributes mentioned above, a Multiple Answer question can have the following options: #### Display Layout Avicenna offers a set of options for the layout of _Multiple Answers_ questions. This feature allows you to customize the look and feel of your questions based on the content of the available answers. For _Multiple Answers_ questions, you can choose either _Checkbox_ or _Button_ layouts. To set it, make sure your question is selected. Then, open the _Properties_ tab from the right side. Find the _Display Layout_ dropdown menu and select the appropriate layout. ![Display layout options for Multiple Answers questions](/assets/survey-questions-multiple-answer-display-layout.png) The following two images show the _Multiple Answers_ question layout in each case. ![The Checkbox layout for Multiple Answers questions](/assets/survey-questions-multiple-answer-checkbox.png) ![The Button layout for Multiple Answers questions](/assets/survey-questions-multiple-answer-button.png) #### Maximum Choices Using this option, you can specify how many choices participants can select at most to answer this question. Participants can select any number of choices between zero (or one, for mandatory questions) and this number as part of their response. #### Exclusive Answer Using this option, you can specify the answer that, when selected, deselects all the other answers, and when any other answer is selected, it would be deselected. #### Answer Randomization You can randomize the selection of the answers within your question using the options available in the `Answer Randomization`. The random selection allows you to choose a subset of answers within your question using the `Included Answer ID(s)` option and also choose a `Selection Count`. Using this, besides the answers that are not part of the `Included Answer ID(s)`, only a subset of the specified answers will be used to construct the question, where the size of the subset is the same as the `Selection Count`. For example, assume your question has seven answers, with IDs from 1 to 7. Also, assume the `Included Answer ID(s)` is set to 3, 4, and 5, and the `Selection Count` is set to 2. With these settings, answers 1, 2, 6, and 7 will always be part of the question, and from answers 3, 4, and 5, only two randomly selected answers will be used to construct the question. #### Random Answer Order You can enable the `Random Answer Order` option. Doing so will randomize the order in which these answers are displayed. Please note that these randomizations happen only once for each [Survey session](../activities/activity-sessions.md) whenever the corresponding Survey is opened. #### Suggested Answers There is a button above the answers in the Edit mode called `Use Suggested Answers`. After clicking on that button, you will see a list of all available suggested answers. By selecting any of them and confirming your decision, the existing answers and their localizations (if any) will be replaced by the answers you just selected. In the image below, `Age` as a suggested answer is chosen. ![Suggested Answers](/assets/survey-questions-suggested-answers.png) #### Adding/Updating Multiple Answers Contents At Once Other than the Suggested Answers option, you can add/update answers by pasting a multi-line text into one of the existing answers. When you paste your text, if the number of non-empty lines after removing extra spaces from the start/end of each line, is less than 2, your text will be pasted as usual. Otherwise, the `Paste Multiline Text` dialog would be opened in which you would have three modes to choose from: - **Create new answers**: It will create new answers based on the non-empty lines in your text after the focused answer. - **Override answers**: It will override the answers with the non-empty lines in your text, including the focused answer. Also, it will create new answers if the number of answers from the focused one to the end is less than the number of those non-empty lines. - **Override empty answers**: It will just override the empty answers starting from the focused one forward. When it reaches a non-empty answer or the end, it will create new answers at that point. ### Single Answer Single Answer questions provide participants with one or more potential answers and allow them to choose only one of them. In addition to the common attributes mentioned above, a _Single Answer_ question can have all the attributes a [Multiple Answer](#multiple-answer) question may have, except the `Maximum Choices`. You can also add/update multiple answers contents at once or use suggested answers, as explained above. ![Single Answer Questions in an Avicenna Survey](/assets/survey-questions-type-single-answer-sample.png) #### Display Layout Similar to the _Multiple Answers_ questions, Avicenna offers a set of options for the layout of a _Single Answer_ question. You can choose _Radio Button_, _Button_, or _Dropdown_ layouts for _Single Answer_ questions. To set it, firstly, make sure your question is selected. Then, open the _Properties_ panel from the right side. Find the _Display Layout_ dropdown menu and select the appropriate layout. ![Display layout options for a Single Answer question](/assets/survey-questions-single-answer-display-layout.png) The following three images show the Single Answer question's layout in each case. ![The Radio Button layout for a Single Answer question](/assets/survey-questions-single-answer-radio-button.png) ![The Button layout for a Single Answer question](/assets/survey-questions-single-answer-button.png) ![The Dropdown layout for a Single Answer question](/assets/survey-questions-single-answer-dropdown.png) ### Text In this type of question, participants are provided with a text box where they can type in a text as their response. In addition to the common attributes mentioned above, a text question can have the following attributes: #### Format Defines a specific format for the response. The value is a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) which the provided answer will be matched against. If not provided, any answer will be accepted. For example, in the screenshot below, the format is specified as `^[a-zA-Z][a-zA-Z][a-zA-Z]$`; hence only three-letter alphabetical strings will be accepted. ![Text Question in an Avicenna Survey](/assets/survey-questions-type-free-form.png) #### Hint A hint is to be shown to the participant for their response to this question. This string will be shown inside the textbox while it's still empty. It's a good practice to use a descriptive hint when a given _Format_ is used. For example, in the screenshot above, the hint is set to `ABC` to indicate that a three-letter alphabetical string is expected. #### Type If it's set to Single Line, the participant would be forced to enter a single line of text as their response. The other option is Multi Line which is the default option. #### Autocomplete Options This option allows you to specify a set of options that participants are very likely going to enter as their response to this question, and Avicenna will provide them to the participants through an autocomplete user interface. Note that this option is only available for single-line text questions. To set the Autocomplete Options, click on this item in the Properties panel to open the Autocomplete Options dialog, and then enter each option in a separate line: ![Text Question Autocomplete Options](/assets/survey-questions-type-free-form-autocomplete-options-box.png) If you set these options, participants will be prompted with the proper options as they start typing their answers to the question: ![Text Question Autocomplete Options Phone Example](/assets/survey-questions-type-free-form-autocomplete-options-sample.png) #### Use Past Answers for Autocomplete If you set your question to show autocomplete options, participants still may enter an answer that is not part of the options you have provided them. In this case, you can instruct Avicenna to automatically add the provided answer to the participant's auto-complete options. In this case, all participants start the study by seeing the same set of options you have provided them via the `Autocomplete Options`. However, as they enter different values as the response to this question, their responses will be added to the set of options, and each participant will receive autocomplete options customized based on their previous responses. ### Number Number questions provide participants with an option to pick a number as their response. In addition to the common attributes mentioned above, Number questions may have the following attributes: #### Step In addition to typing the number, participants have the option to change the selected number by pressing the up or down arrow (as shown in the image below). Each press on the top and down arrow increases or decreases the selected value by the amount specified here. For example, if the question asks about age, each tap on the up or down arrow can increase or decrease the shown value by one year. #### Minimum The minimum acceptable value as an answer. #### Maximum The maximum acceptable value as an answer. #### Default If provided, pressing the up or down button starts the increment or decrement from this value. If skipped, the maximum of 0 and the Minimum value will be used. #### Display Unit The unit for this number. The text specified here will be shown next to the number selected by participants. For example, in the screenshot below, the Display Unit is set to `Years`. ![Number Questions in an Avicenna Survey](/assets/survey-questions-type-number-sample.png) ### Mass Mass questions provide participants with an option to pick a Mass value (in KG or LBs) as their response. Using Mass questions instead of simple Number questions where possible not only provides a better user interface for participants but also simplifies the analysis in many ways, such as unit conversion. In addition to the common attributes mentioned above, a Mass question can have the following attributes: #### Unit The default unit of the response. It can be either `kg` or `lbs`. #### Step Similar to [Number](questions.md#number) questions, this allows participants to increase or decrease the value shown by the specified amount. #### Minimum The minimum acceptable value as an answer is in the default unit. #### Maximum The maximum acceptable value as an answer is in the default unit. #### Default See [Number](questions.md#number) questions. ![Mass Questions in an Avicenna Survey](/assets/survey-questions-type-mass-sample.png) ### Length Length questions provide participants with an option to pick a length value (in metric or imperial) as their response. Similar to [Mass](questions.md#mass) questions, using Length questions instead of a simple [Number](questions.md#number) question where possible not only provides a better user interface for participants, it also simplifies the analysis in many ways, such as unit conversion. In addition to the common attributes mentioned above, a Length question has the following attributes: #### Unit The default unit of the response. It can be either `cm` for metric or `ft_in` for imperial. #### Step Similar to [Number](questions.md#number) questions, this allows participants to increase or decrease the value shown by the specified amount. #### Minimum The minimum acceptable value as an answer is in the default unit. #### Maximum The maximum acceptable value as an answer is in the default unit. #### Default See [Number](questions.md#number) questions. ![Length Question in an Avicenna Survey](/assets/survey-questions-type-length-sample.png) ### Visual Analog Scale (VAS) Visual Analog Scale (or VAS, for short) questions provide participants with a slider that they can use to choose their response. By default, the number chosen by the participant is shown above the slider. Optionally you can define a label for each range of numbers (e.g., `Too hard` for answers between 0 to 2), and the slider shows the label for the responses in that range. In addition to the common attributes mentioned above, a VAS question can have the following attributes: #### Layout If set to "Vertical", Avicenna will show a vertical slider instead of a horizontal slider. For vertical sliders, the bottom represents the minimum value, and the top represents the maximum. The following images show the VAS question with image anchors in horizontal and vertical layouts. ![A VAS Question with a Horizontal Layout](/assets/survey-questions-vas-horizontal.jpg) ![A VAS Question with a Vertical Layout](/assets/survey-questions-vas-vertical.jpg) #### Maximum The upper bound for the number that participants can choose. It can be any number (integer or decimal) greater than the `Minimum`. Defaults to 100. Maximum will always be selectable even if it's not reachable by the Steps from the Minimum. #### Minimum The lower bound for the number that participants can choose. It can be any number (integer or decimal) less than the `Maximum`. Defaults to 0. #### Step You can use this attribute to specify how many steps the slider should jump every time the participant moves it. By default, the slider moves by 1 step in either direction on each move. It can be any number (integer or decimal) greater than or equal to 0.000000001. Steps start from the Minimum value. So, if you set the Step to 6 and the Minimum to -100, the first step would be -100, and the next one would be -94 if the Maximum is greater than or equal to -94. #### Show Selection Value In the context of VAS questions, the `Show Selection Value` refers to displaying the numeric value associated with the respondent's selection on the VAS scale. When a respondent selects a point on the scale, this feature will show the numeric value of their selection, providing immediate feedback on their choice. #### Anchor Type Anchors in a VAS question allow you to set labels to each end of the slider of the question and describe each spectrum better. Avicenna offers text and image as two options for anchor type. This can be applied to VAS questions with both horizontal and vertical layouts. If _Text_ is selected, you can write a text in the fields provided for the left and right anchors. If you intend to add images to the anchors, you need to select _Image_ as the anchor type. **Text Anchors** To add texts as anchors, make sure your VAS question is selected, then open the _Properties_ menu from the right-side panel, select _Text_ for the _Anchor Type_, and write relevant text for the right and left anchors. ![Selecting Text as Anchor Type in VAS Questions](/assets/survey-questions-vas-text-anchor-type.png) **Image Anchors** To add images to the anchors of the VAS question, simply set the _Anchor Type_ to _Image_ and upload images for the right and left anchors. ![Selecting Image as Anchor Type in VAS Questions](/assets/survey-questions-vas-image-anchor-type.png) #### Right Anchor This text will be shown on the right side of the anchor (or on the top of the anchor, if a vertical layout is used) of the VAS question. Defaults to empty text. #### Left Anchor This text will be shown on the left side of the anchor (or on the bottom of the anchor, if a vertical layout is used) of the VAS question. Defaults to empty text. #### Show Selection Label Selection labels are spaced and placed along the length of the VAS line. These labels are important because they provide more nuanced and specific information about the range of responses the VAS question is measuring. Just like the anchors, the labels can also have `Text` or `Image` type. After choosing the type, there are two fields to be filled in. The `Label` and the `Lower Bound`. You do not specify the upper bound here. Rather, the upper bound is calculated as the next label's lower bound exclusively. Lower bounds can be any number (integer or decimal) and they must lie between the `Minimum` and `Maximum` of the VAS question. For example, consider a VAS question, that measures satisfaction with a product or service, the slider is set to accept numbers from 0 to 100, `Step` is 1, and the labels are set to the following: ```text Very dissatisfied -> 0 Somewhat dissatisfied -> 20 Neutral -> 40 Somewhat satisfied -> 60 Very satisfied -> 80 ``` If the participant moves the slider to select any number between 0 and 19, the label _Very dissatisfied_ will be shown. If the participant moves the slider between 20 and 39, the label _Somewhat dissatisfied_ will be shown. Similarly, the labels _Neutral_, _Somewhat satisfied_, and _Very satisfied_ will be shown for choices between 40 to 59, 60 to 70, and 80 to 100, accordingly. ![Visual Analog Scale Question in an Avicenna Survey](/assets/survey-questions-type-vas-sample.png) ### Calendar Calendar questions allow participants to select a date, a time of day, or a combination of date and time, as their response. It also supports selecting a time or date period. ![Calendar Question in an Avicenna Survey](/assets/survey-questions-type-calendar-sample.png) In addition to the common attributes mentioned above, a Calendar question has the following attributes: #### Selector Determines whether this Calendar question should allow participants to only pick dates, pick a time, or pick a combination of date and time. #### Minimum The minimum value this Calendar question can accept. This only limits the day the participant can select (assuming the `Selector` is for `Date` or `Date/Time`), and the participant can select any time they prefer. Therefore if the `Selector` is `Time`, this value will be discarded. If the minimum day is expected to be the day the participant answers the question, check `Use participant's today` in the Properties panel. This way, the minimum date will be the current date when the participant is answering the question. #### Maximum The maximum value this Calendar question can accept. This only limits the day the participant can select (assuming the `Selector` is for `Date` or `Date/Time`), and the participant can select any time they prefer. Therefore if the `Selector` is `Time`, this value will be discarded. If the maximum day is expected to be the day the participant answers the question, check `Use participant's today` in the Properties panel. This way, the maximum date will be the current date when the participant is answering the question. #### Period If selected, the participant will be asked to choose a period rather than a single time. The start and end of the selected period will depend on the `Selector`, and it can be either: - A date range, e.g. Jun 1st, 2019 to Jun 5th, 2019 - A time range, e.g., 10:30 to 13:50 - A date and time range, e.g. Jun 1st, 2019 10:30 to Jun 5th, 2019 13:50 #### Minute Interval The time interval the participant can choose. The options are 1, 5, 10, 15, 20, 30, and 60. If set to 1, the participant can pick any minute of a given hour. If set to 15, the participant can only choose the quarters, i.e., 10:00, 10:15, 10:30, and 10:45. If set to 60, the participant can only choose hours, e.g., 10:00 or 11:00. ### Image Image questions allow participants to take a picture as their response. Alternatively, they can choose a previously captured image from their device's image library. ![Image Question in an Avicenna Survey](/assets/survey-questions-type-image-sample.png) ### Video Video questions allow participants to capture a video as their response. Alternatively, they can choose a previously recorded video from their device's video library. ### Audio Audio questions allow participants to record an audio as their response. Alternatively, they can choose a previously recorded audio from their device's audio library. ![Audio Question in an Avicenna Survey](/assets/survey-questions-type-audio-sample.png) #### Audio File Format and Specifications The file format and specifications of the recorded audio responses vary depending on the device and app used: **Chrome/Edge Users** - **File Type**: MKA (.mka) - **MIME Type**: audio/x-matroska - **EBML Version**: 1 - **Doc Type**: webm **Firefox Users** - **Format**: Ogg (typically uses Vorbis or Opus codec) **Android App Users** - **Sampling Rate**: 44100 Hz - **Bit Rate**: 96000 bps - **Format**: MPEG-4 (AAC encoder) **iOS App Users** - **Format**: MPEG4-AAC - **Sample Rate**: 12000 Hz - **Channels**: 1 (Mono) - **Quality**: Medium ### Audio/Text Audio/Text questions provide participants with the option to either type their response or record it as audio using the microphone. Many attributes available to Audio/Text questions are similar to the ones for a Text question. ![Audio/Text Questions in an Avicenna Survey](/assets/survey-questions-type-audio-text-sample.png) For the audio file format and specifications, please refer to the [Audio File Format and Specifications](#audio-file-format-and-specifications). ### Barcode Barcode questions allow participants to scan a barcode or QR code as their response. The following image shows the user interface for Barcode questions in a Survey. When a participant presses the `Scan Barcode` button, Avicenna will start the camera, allowing the participant to scan the barcode. The value of the barcode will be shown to the participant and taken as the response to the question. ![Barcode Question in an Avicenna Survey](/assets/survey-questions-type-barcode-sample.png) ## Adjusting Question Content ### Text The text size of the Survey is chosen based on the text size of the device. This will provide the participants with a consistent user interface as experienced in the rest of their apps. Avicenna offers a few options to refine this for each question. For example, a text can be set to be shown slightly larger or smaller than the device's default text size, or it can be set to be bold or italic. These changes can be done using HTML tags in the question content. Avicenna currently supports the following HTML tags as part of the question content: p, ul, ol, li, div, span, strong, b, em, cite, blockquote, dfn, i, small, code, pre, a, u, del, s, sup, sub, h1, h2, h3, h4, h5, h6, img, br The text editor in the Survey Editor allows you to apply most of these modifications using a graphical interface: ![Question Content Editor for Avicenna Surveys](/assets/survey-questions-content-editor.png) Note that if you use a URL in your question content, the target link should be HTTPS. HTTP links may not work in some versions of Android and iOS. ### Multimedia Each of the questions described above consists of a content section, which includes the text of the question being posed. The content can include any combination of text, images, and video. To add images, simply click on the image icon in the editor toolbar, and upload your image from your computer. For video, Avicenna only supports videos from YouTube. You need to upload your video to YouTube first and then add its link to your question content using the editor. ![Adding Video to Your Question Content](/assets/survey-questions-content-editor-video.png) Avicenna will add a video player to your question content and load the video thumbnail in it, as shown below: ![Question Content with a Video](/assets/survey-questions-video-content.png) Note that even though Avicenna expects you to upload your video to YouTube and provide the link, the Avicenna app will not ask the participant to open the YouTube app to see the video. The video player will be fully embedded in Avicenna's Survey question. Here, YouTube will only host the video and provide it to Avicenna to be played for the participant. If your question content contains a video, Avicenna records all interactions participants have with that video. This includes how long, in total, the participant watched the video, e.g., 110 seconds. This may be longer than the video length, which means the participant watched parts of the video more than once. It also includes how the video was watched. This will be the start and end time of each watch session. For example, assume the video is 120 seconds, and the participant watches it from 0 to 30th second and then jumps to 75th second and watches to the end. In this case, you will get an array as follows: ```text [ [0, 30], [75, 120] ] ``` ### Integrating Audio into Survey Questions You can attach an audio file to each question in your survey. This allows participants to listen to the question instead of reading it. This feature can be very helpful for illiterate participants or those with reading difficulties. Note that while many platforms offer screen readers that provide a similar feature, the screen reader is not available in all languages, and the pronunciation is not strictly controlled. The advantage of this feature over standard screen readers is that you can control exactly how the question's content should be read in each language that your study supports. #### Uploading an Audio File - **Initiate Audio Upload**: Click on the `Add Audio (Microphone)` button located in the question's toolbar. - **File Selection and Upload**: Choose a `.mp3` audio file. Make sure it does not exceed 30 MB. Confirm the upload by clicking the `Add` button to embed an audio player within the question content. ![Uploading an Audio for a Question](/assets/survey-questions-content-editor-uploading-audio-for-question.png) #### Using Previously Uploaded Audio - **Select Existing Audio**: In the `Add Audio` dialog, browse and select from the list of previously uploaded audio files. - **Embed Audio into Question**: Confirm the selection by clicking `Add` integrating the chosen audio directly into the question. #### Recording Audio Directly - **Start Voice Recording**: Access the voice recording feature by selecting the `Record Voice` button within the `Add Audio` dialog. - **Voice Recording and Integration**: Record your voice. Recordings cannot be longer than 30 minutes. Finish and embed the recording in the question by clicking on the `Add` button. ![Recording Audio for a Question](/assets/survey-questions-content-editor-recording-audio-for-question.png) #### Removing Audio from a Question - **Audio Removal**: To delete an embedded audio, position the cursor immediately after the audio player and press Backspace, removing both the audio and its player from the question. ### Placeholders In the [Criteria](../activities/criteria.md) section, we discussed using Survey ID and Question ID to identify and use the last response to a specific question in your Criteria conditions. For example, `Q1_2` refers to the last response to question 2 of Survey 1. Similarly, you can use placeholders within your question content to dynamically insert responses or specific information relevant to the participant, enhancing the personalization of survey questions. Placeholders are formatted as `{{placeholder_name}}` and are replaced with dynamic content when the question is presented to the participant. Avicenna supports these placeholders: - `{{Qm_n}}`: Refers to the last response to a survey question, in which `n` is the question ID and `m` is the survey ID. The placeholder will be replaced based on the question type and specific rules described below. Also, you can use the alternative format (`{{Qn}}`) if the placeholder is used in the same survey as the survey of question `n`. - `{{user_fname}}`, `{{user_lname}}`, and `{{user_name}}`: Used to insert the participant's first name, last name, or full name, respectively, if the participant provided them in their profile. - `{{loop_value}}`: Inserts the value related to the current iteration in a loop section. You can read more about `loop_value` [here](flow-control.md#looping-through-a-section). For example, consider the following question content: ```text Hi {{user_fname}}. Which of the following steps are you going to take toward your social goal of "{{Q12_6}}"? ``` Assuming the response to question #6 of Survey #12 has been _Making a new friend by going to the events you are interested in_ and the participant's first name is _Bill_, the question above will be presented to the participant as follows: ```text Hi Bill. Which of the following steps are you going to take toward your social goal of "Making a new friend by going to the events you are interested in"? ``` Avicenna replaces `{{Qm_n}}` placeholders according to the type of question to which they refer and the context of the question. Currently, you can use placeholders for the response to questions of the following types: - **Text**: The placeholder is replaced with the last textual response to the question. - **Audio/Text**: The placeholder is replaced with the textual part of the last response to the question. Audio-only responses won't be displayed. - **Multiple Answer**: The placeholder is replaced with a list of chosen answers' contents from the last response, in the order they were selected. Image answers won't be displayed. - **Single Answer**: The placeholder is replaced with the content of the selected answer from the last response. Image answers won't be displayed. - **Visual Analog Scale (VAS)**: The placeholder is replaced with the last number response to the question. - **Number**: The placeholder is replaced with the last number response to the question. - **Mass**: The placeholder is replaced with the last number response to the question and the participant's selected unit. - **Length**: The placeholder is replaced with the last number response to the question and the participant's selected unit. - **Barcode**: The placeholder is replaced with the last textual code response to the question. - **Calendar**: The placeholder is replaced with the last date, time, date/time, or period response to the question. If question `n` of survey `m` is part of a looped section, the `{{Qm_n}}` placeholder will be replaced with an ordered list of responses for each iteration of that loop, according to the rules for the question types above. ## Troubleshooting ### YouTube videos don't play on the Android app For YouTube videos to play properly in survey questions on Android apps, participants need to have both Google Play Services and the YouTube app installed and updated. If these requirements are not met, participants may see errors like "Could not load the video". --- sidebar_position: 2 --- # Flow Control In Avicenna, a Survey consists of one or more sections that are displayed in sequence to the participants. By default, these sections are shown one after another up to the last section, at which point the Survey Activity session is completed. There are multiple ways to modify the flow of Surveys based on participants' responses, including: - Showing or skipping a section or question. This can be done via: - Showing or skipping a section or question using Criteria - Showing or skipping a question using the Enable Questions option - Changing the flow of sections through the Section and Question properties - Looping through a section - Section and Question randomization Below we explain each of these approaches in more detail. ## Showing or Skipping a Section or Question There are three methods for organizing your Survey structure in Avicenna. The most versatile approach is [Criteria](../activities/criteria.md) which lets you display or skip questions or sections based on answers to earlier questions, either within the current Survey or from previous Surveys in the study. Although powerful, this method can be complicated and challenging to manage. Avicenna also provides simpler options for basic showing and skipping patterns, allowing you to show or skip specific questions or alter the Survey flow. If you find these options easier than using criteria, feel free to use them instead. The next sections will discuss each method in greater detail. ### Showing or Skipping a Section or Question Using Criteria Criteria enables you to set a condition that decides when a Survey section or question should be displayed or skipped. When a Criteria is applied to a section or question, Avicenna checks the condition right before showing that part of the Survey. Based on the participants' answers up to that moment, the condition is assessed as either True or False. This outcome decides if the section or question should be shown. If the condition is True, Avicenna displays the section or question, while if it's False, Avicenna moves on to the next section or the subsequent question. :::info If the section or the question with the criteria is the last, and the criteria are evaluated as False, Avicenna will finish the Survey. ::: Now, we are going to demonstrate how you can define a Criteria for sections. We are using the questions below in our Survey: ```text Section ID: 1 (QID-1 - Multiple Answer): Have you been told by a doctor that you have any of the following? A ID: 1: Depression A ID: 2: Generalized anxiety disorder A ID: 3: Social phobia A ID: 4: Agoraphobia A ID: 5: Post-traumatic stress disorder A ID: 6: Panic disorder A ID: 7: Obsessive-compulsive disorder Section ID: 2 (Questions related to the "Obsessive-compulsive disorder") (QID-2 - Information): The following statements refer to experiences that many people have in their everyday lives. Please CIRCLE the number that best describes HOW MUCH that experience has DISTRESSED or BOTHERED YOU DURING THE PAST MONTH: (QID-3 - Single Answer): Unpleasant thoughts come into my mind against my will, and I cannot get rid of them. A ID: 1: Not at all A ID: 2: A little A ID: 3: Moderately A ID: 4: A lot (QID-4 - Single Answer): I think contact with bodily secretions (sweat, saliva, blood, urine, etc.) may contaminate my clothes or somehow harm me. A ID: 1: Not at all A ID: 2: A little A ID: 3: Moderately A ID: 4: A lot ``` In this example, we want to have Section 2 prompted only to those participants who choose _Answer ID 7: Obsessive-compulsive disorder_ to Question 1. First, make sure that the second section is selected, and then go to _Section Properties_. Then find the Criteria box, and write `Q17139_1 == 7`. Note that 17139 refers to the ID of the current Survey, 1 refers to Question 1 in this Survey, and 7 represents the answer ID 7 ("Obsessive-compulsive disorder"). ![Using Criteria to Change the Sections Flow](/assets/survey-flow-control-section-properties-criteria-change-sections-flow.png) Based on this, Section 2 will be prompted to the participants as long as they choose Answer ID 7 in the first question. Criteria can also be used to skip or show a question. We are using the following questions as an example to demonstrate this. ```text (QID-1 - Single Answer): Have you ever used a set of questionnaires to check your child's motor skills? A ID: 1: Yes A ID: 2: No (QID-2 - Multiple Answer): Which of the following questionnaires have you used to check your child's motor skills?? A ID: 1: The Early Motor Questionnaire (EMQ) A ID: 2: ASQ - Ages and Stages A ID: 3: The Child Evaluation Checklist ``` In this example, we want Question 2 to be available for the participants who have chosen _Yes_ as the answer to Question 1. So, after selecting Question 2, open _Question Properties,_ and then write _`Q17855_1 == 1`_ in the Criteria box. Remember that 17855 is the ID of the current Survey, the first 1 refers to Question ID 1, and the second 1 refers to the answer ID 1 (Yes) in Question 1. ![Using Criteria to Change the Questions Flow](/assets/survey-flow-control-question-properties-criteria-change-questions-flow.png) ### Showing or skipping a Question using the Enable Questions Option Avicenna allows you to show or hide the questions within a given section based on the response provided for another question. Any potential answer for a Single or Multiple Answer question has a property called _Enable Questions_, which receives a list of question IDs to be enabled if the participant selects this answer. :::info Note that all the questions being shown or skipped using the Enable Questions option are expected to be in the same Section as the Single or Multiple Answer question, which contains the potential answer. ::: For example, assume that you want to know if participants have experienced coughing recently and, if yes, whether this was due to low air quality. You can create a Survey as follows: ```text (QID-1 - Single Answer): Did you experience coughing or wheezing last week? A ID: 1: Yes A ID: 2: No (QID-2 - Single Answer): Do you believe that it is likely that these symptoms were related to poor air quality? A ID: 1: Yes A ID: 2: No ``` You want Question 2 to be shown only if the participants select _Yes_ as their answer to Question 1. To do this, after selecting Question 2, open _Properties_ from the right-side panel. Go to _Question Properties_, scroll down, and turn the _Enabled_ toggle off. This instructs Avicenna to skip the question by default. ![Disabling questions from Question Properties](/assets/survey-flow-control-question-properties-disable.jpg) Then, go back to Question 1. Open the _Properties_ tab, and select Answer from _Question Properties_. Next, go to the _Answer ID 1_ section, where you should choose 2 in the _Enable Questions_ box. ![Enabling questions from Question Properties](/assets/survey-flow-control-question-properties-enable-questions.jpg) By doing this, Avicenna will show Question 2 to the participants only if they have already responded Yes to Question 1. ### Changing the Flow of Sections through the Section and Question Properties Each section specifies what section should be shown next or whether the Survey should be marked as completed after the section is done. By default, each section points to its next section or finishes the Survey if it is the last section. You can change this flow using the _Next Section ID_ property of each section. For example, assume that you are working on a Survey with the following sections and questions: ```text Section ID: 1 (QID-1 - Single Answer): Do you receive treatment for heart disease (For example, angina, heart failure, or heart attack)? A ID: 1: Yes A ID: 2: No (QID-2 - Single Answer): Does your heart disease limit your activities? A ID: 1: Yes A ID: 2: No Section ID: 2 (QID-3 - Single Answer): Do you receive treatment for high blood pressure? A ID: 1: Yes A ID: 2: No Section ID: 3 (QID-4 - Single Answer): Do you have regular physical activity? A ID: 1: Yes A ID: 2: No ``` The default behavior is that the participant is first presented with all questions of section 1, followed by section 2 and section 3. However, this default flow of sections can be modified by using the _Next Section ID_ in _Section Properties_. For example, assume that you want to show section 3 after completing section 1 and skip presenting section 2 to the participants. To do this, first, you need to make sure that the intended section (Section 1 in our example) is selected. The selected item is shown with a blue border. Then, open _Properties_ from the right-side panel and select 3 for _Next Section ID_. By doing this, Avicenna will take participants to Section 3 after completing Section 1. ![Changing the next section from Section Properties](/assets/survey-flow-control-section-properties-next-section-id.png) It is also possible to override the flow of the upcoming sections from _Question Properties_. For example, assuming we want to ask questions about blood pressure only if the person reports not having prior heart disease. To do this, choose Question 1 (from the example above) and open _Properties_ from the right-side panel. After that, select _Answer_, go to _Answer ID 1 ("Yes")_, and choose _Section ID: 3_ for _Next Section ID_. ![Changing the next section from Question Properties](/assets/survey-flow-control-question-properties-next-section-id.png) By doing this, if _Yes_ is selected in Question 1, i.e., the participant reports having heart disease, Section 2 will be skipped, and Avicenna will take the participants to Section 3. Please note that in this case, all remaining questions of Section 1 will still be asked. So the participant still will see Question 2 (“Does your heart disease limit your activities?”), no matter what they reply to Question 1. :::caution Any potential answer to a Single or Multiple Answer question can define the index of the section, which should be shown following the current section. If each answer in a Multiple Answer question defines different indexes for the next section, the last answer selected by the participant will override the previous value for the next section. This leads to nondeterministic behavior, which is not suggested. If answers are expected to change the index of the next section in a Multiple Answer question, you need to make sure that they all point to the same section. ::: ## Looping Through a Section You can configure a given section to be a _Loop Section_. In this case, Avicenna will iterate through the loop section X times, where X is based on the response to the _Source Question_. For example, consider the following Survey: ```text Section ID: 1 (QID-1 - Single Answer): Have you eaten any processed food since last week? A ID: 1: Yes A ID: 2: No (QID-2 - Number): How many processed foods have you consumed? Section ID: 2 (QID-3 - Text): What is the name of the food? (QID-4 - Image): Take a picture of the food. ``` Here, in section 2, you want to ask the participant to report details of each fast food they have consumed. So you can set section 2 as a loop section and configure it to be looped based on the response to question 2. To do so, after selecting section 2, enable the _Loop Through this Section_ under the _Properties_. Then, choose Question ID 2 as the _Source Question ID_. ![Looping a section from Section Properties](/assets/survey-flow-control-section-properties-loop-through-section.jpg) In this case, Avicenna will ask the questions in section 2 as many times as the number of times that the participant has eaten processed food in the past week. Note that the Source Question can be either a [Number](questions.md#number) or a [Multiple Answer](questions.md#multiple-answer) question. If you choose a Number question, the loop section will be looped X times, where X is the response to the Number question. If you choose a Multiple Answer question, the loop section will be looped once for each chosen option. :::info If the reply to the Number Source Question is 0, or no option is chosen in a Multiple Answer Source Question, the loop section will be skipped. ::: Questions inside a loop section also support specific [placeholder](questions.md#placeholders): `{{loop_value}}`. This placeholder allows you to refer to the option being asked inside the loop section. In the case of Number Source Questions, `{{loop_value}}` will be replaced by an ordinal iteration number, i.e., `1st`, `2nd`, `3rd`, `4th`, and so on. In the case of Multiple Answer Source Questions, this placeholder will be replaced by the content of the chosen answers. Let's continue our example above. To use this placeholder in our example, select the question and click on _Edit_, which takes you to the content box. While you are writing the content of the question, tap on _Add Placeholder_, and choose _Loop Value_. ![Adding Loop Value as a Placeholder](/assets/survey-flow-control-add-placeholder-loop-value.jpg) Your questions should look like this: ```text Section ID: 2 Q ID: 3: Text: What is the name of the {{loop_value}} food? Q ID: 4: Image: Take a picture of the {{loop_value}} food. ``` For example, if the participant has reported eating two processed foods, the flow of the questions will be as follows: ```text Section ID: 1 Q ID: 2: Number: How many processed foods have you consumed? Answer: 2 Section ID: 2 - Iteration 1: Q ID: 3: Text: What is the name of the 1st food? Q ID: 4: Image: Take a picture of the 1st food. Section ID: 2 - Iteration 2: Q ID: 3: Text: What is the name of the 2nd food? Q ID: 4: Image: Take a picture of the 2nd food. ``` ## Section and Question Randomization We have previously discussed [Section Randomization](README.md#section-randomization). Similarly, you can randomize the selection of questions within each section using _Question Randomization_. To randomly select a subset of questions within your section, you need to use the _Included Question ID(s)_ and _Selection Count_ options. For example, assume that your Survey section has seven questions with IDs from 1 to 7. You want questions 1,2,3 and 4 to always be in the Survey. From questions 5, 6, and 7, you want only one of them to be randomly available in the section. To do so, open _Section Properties_ and go to _Question Randomization_. Next, select questions 5, 6, and 7 from the _Included Question ID(s)_, and set the _Selection Count_ to 1. With these settings, this section of the Survey will consist of questions 1, 2, 3, 4, and one of the last three questions (5, 6, and 7). ![Question randomization](/assets/survey-flow-control-section-properties-question-randomization.jpg) You can also enable the _Random Question Order_ option to randomize the order in which these questions are displayed. Keep in mind that these randomizations happen only once for each Survey session. --- sidebar_position: 3 --- # View Responses ## Activity Responses Page In this section, we explain how you can review the responses submitted by each participant using the Researcher Dashboard. We will also describe the metadata stored with each Survey response. You can view participants' responses using the _Activity Responses_ page on the Researcher Dashboard. On the top of the page, you can choose the Survey you want to view the responses for: ![Survey Responses Preview](/assets/survey-view-responses-survey-responses-page.png) Note that you can't choose more than one Survey from the list because the columns for each Survey are different from the other ones. You only can export and download the responses for multiple Surveys at once. Doing so will create a ZIP file that contains multiple CSV files, one for each of the Surveys you have selected here. In the Survey Responses table, each column represents a question in the Survey, the first column shows the Survey sessions, and in the next columns, each cell is for the participant's response to that particular question in that particular session. You can click on the arrow button of each cell to see more information about it, if any. In each answer cell, there is a drop-down menu next to the given answer. By clicking on it, you'll see the extra details of that answer, such as the time that this answer was given or the location in which this response was provided (given that you have enabled the [Capture Location option](README.md#capture-location) for your Survey): ![View Answer attributes](/assets/survey-view-responses-survey-responses-answer-attributes.png) Similarly, if you click on each cell of the first `column`, you can see the attributes for the relevant participant, such as the Device ID, Participant Status, Device Model, and other related data: ![View response attributes](/assets/survey-view-responses-survey-responses-user-attributes.png) If a question has been answered in multiple loop iterations, you can see the answer given in each iteration along with an option to view the complete response history. For instance, in the third question (Q3: Question 3 of Survey 21218), you can observe two iterations, indicating that the user answered this question twice, with responses 'Pizza' and 'Hamburger' for the first and second iterations, respectively. This setup helps to track and analyze the patterns in responses over multiple loops within the same session. ![View Responses of Loop-iterated Questions](/assets/survey-view-responses-loop-iterated-questions.png) Questions can be left unanswered due to various reasons and when viewing the responses, you can see the reasons for the unanswered questions inside the response cell. Here are the possible reasons for an unanswered question: - **Skipped** specifies that the question was skipped by the respondent. - **Due to question criteria** specifies that the question was not shown to the respondent because the question's criteria had been evaluated as false. - **Due to section criteria** specifies that the question was not shown to the respondent because the containing section's criteria had been evaluated as false. - **Due to question randomization** specifies that the question was not shown to the respondent because the question was omitted due to randomization. - **Due to section randomization** specifies that the question was not shown to the respondent because its containing section was omitted due to randomization. - **Due to disabled question** specifies that the question was not shown to the respondent because the question was disabled. - **Due to zero section loop iterations** specifies that the question was not shown to the respondent because based on the response to the loop source question, the section was not looped over. - **Due to sections flow** specifies that the containing section was skipped by the `Next Section ID` of a question's answer or a section. - **Due to session status** specifies that the corresponding session was `Expired`, `Canceled`, or `Blocked` before the respondent could answer the question. This can also be due to the session being `Unanswered` or `In-Progress`. :::note The response cell for unanswered questions that were submitted before we introduced this categorization will be shown as "Unanswered - Due to unknown reason". ::: :::note The reasons behind unanswered questions will only be visible in the researcher dashboard. At the moment, exported files based on survey responses will show unanswered questions empty as before. ::: ## Data Filtering After selecting the Survey you want to view responses for, clicking on the `Filter` button allows you to filter, sort, and organize your data as you want. Also, you can export the responses as a ZIP file when necessary. The ZIP file will contain a CSV file for the textual information of the responses. On the other hand, any media-based response file (such as image, audio—which includes the audio part of Audio/Text responses—and video) will be in a separate folder named `response-files` under the ZIP file. The CSV will also include the paths to the media-based response files for easy reference. For more information on how to filter your data, see [Data Filtering](../study-setup-and-deployment/data-filtering.md). ## Survey Data Structure When a Survey is prompted to a given participant, Avicenna opens a session that is associated with that Survey and to that participant. When the session is concluded, either because the participant completed the Survey, the Survey expired after a certain time, or for any other reason, the Avicenna app collects all available responses and uploads the session together with its responses to the Avicenna servers. Each session has certain metadata that describes it. In turn, each response and question in a session also has certain metadata for itself. Below we describe this metadata in detail: ### Session Metadata The following describes the metadata stored with each session: #### User ID The Avicenna ID of the participant associated with this session is stored internally as `user_id`. #### Activity ID The ID of the Survey Activity for this session. Also indicates the expected questions and responses. Stored internally as `activity_id`. #### Version The Version of the Survey. If you modify your Survey while having active participants in the study, Avicenna uses versions to track who responded to which Version of your Survey. Internally stored as `version`. #### Unique ID A unique identifier for the session, stored internally as `uuid`. #### Device ID The ID of the device used by the participant to complete this session. Useful when a participant uses multiple devices for the study. Stored internally as `device_id`. #### Scheduled Time The time when the Survey was planned to be prompted to the participant. For Time-Triggered Surveys, this time is predetermined. For other Triggering Logics, such as proximity triggered, this time is recorded when the session is first created. Stored internally as `scheduled_time`. #### Prompt Time Refers to the specific time when the Survey is intended to be presented to the participants. #### Record Time The time when this session was concluded, either as completed, expired, blocked, or canceled (see [here](../activities/activity-sessions.md) for the definition of each of these statuses), which is internally stored as `record_time`. The session Status, internally stored as `status_id`, with possible values: - `Completed`: The Survey was completed by the participant. - `Canceled`: The participant explicitly canceled responding to the Survey. - `Expired`: The Survey was not responded to within the allocated time. - `Blocked`: The Survey could not be triggered due to another active session for the same Survey for this participant. #### Triggering Logics ID The ID of the Survey's Triggering Logics that initiated this session is helpful when you anticipate your Survey being activated by various triggering methods. It enables you to identify which specific Triggering Logics was responsible for starting the current Survey session. #### Triggering Logics Type Refers to the type of Triggering Logics that is used for the current Activity. For more information on Triggering Logics Types check the [Triggering Logics](../activities/triggering-logics.md) page. ### Response Metadata Each session contains a set of responses, one for each answer given by the participant. The metadata stored with each response is detailed below. Not all responses will have all of this information. For more about the response structure, the meaning of each field, and the expected hierarchy, consult the [Survey Response schema](https://avicennaresearch.com/media/survey_content/response_schema.json). #### Question ID The ID of the question corresponding to the response, stored internally as q_id. #### Question Type ID The ID of the type of question that this response belongs to. It can be one of the following values: - 0 - Single Answer - 1 - Information - 2 - Multiple Answer - 3 - Text - 4 - Number - 5 - Image - 6 - Audio - 7 - Video - 8 - Visual Analog Scale - 9 - Mass - 10 - Length - 11 - Audio & Text - 12 - Barcode - 13 - Calendar Internally stored as `q_type_id`. #### Question Content The content of the question that is posed to the participant. This may vary between sessions if the question features dynamic content, meaning the question content can change each time it is asked. Stored internally as `q_content`. #### Answer ID The ID of the answer chosen by the participant. This is only available for _Single Answer_ and _Multiple Answer_ questions. Stored internally as `answer_id`. #### Answer Content The content of the participant's answer. It can be a number (for number, mass, and length questions), a date (for calendar questions), or text (for text and barcode questions). Stored internally as `answer_content`. #### Answer URL The URL of the media submitted by the participant as their response to the question. Depending on the question type, the URL may point to an image, audio, or video file. Stored internally as `answer_url`. #### Response Time The time when the participant provided this response. It falls between the session's _scheduled time_ and the _record time_. Stored internally as `response_time`. #### Loop Count The number of iterations the participant responded to this question. This applies when the question is part of a section located in a loop, meaning it is presented to the participant multiple times within the same session. Stored internally as `loop_count`. #### Iteration The loop iteration index in which the participant responded to this question. This applies when the question is part of a section located in a loop, meaning it is presented to the participant multiple times within the same session. Stored internally as `iteration`. #### Location The latitude, longitude, speed, and accuracy value for the GPS coordinates of the participant while responding to this question. This is only captured if the Survey is set to geo-tag the responses. It also requires the participant to grant the Avicenna app the necessary permissions to access GPS. Internally stored as `location`. #### Media Interactions If the question content contains any videos, this attribute indicates how many times the video was watched and which parts were viewed. Stored internally as `media_interactions`. #### Preferred Unit The unit was chosen by the participant when responding to the question. For `Mass` questions, it can be `Kg` or `Lbs`, while for `Length` questions, it can be `cm` or `ft` & `in`. This field is not defined for other question types. Stored internally as `preferred_unit`. ## Viewing Survey Response History Avicenna records any modifications to survey responses, and allows you to track changes for each response within your surveys. This feature, called Survey Response History, helps ensuring the accuracy of responses, and also offers insights into participant behavior. To view the history of a survey response click on the arrow in its cell and then the `View` option under the `Response History` section. By following these steps, you will be able to see the chronological modifications on the survey answers. The response history shows the previous **Submitted** or **Saved** responses. ### Response History Details The detailed view of a response's history includes the following data elements: - [Response Time](#response-time) - [User](#user-id) - [Answer](#answer-content) (and in case there's no answer, the reason behind it as mentioned under [Activity Responses Page](#activity-responses-page)) - [Question Content](#question-content) - [Location](#location) - [Question Content Media Interaction](#media-interactions) ![Response History Details](/assets/view-responses-response-history-details.png) ## Commenting on Survey Responses Researchers can add comments to survey responses, facilitating communication and collaboration with other researchers. To view the existing comments on a survey response or comment on it, whether it's for a simple question or a question in a [loop](flow-control.md#looping-through-a-section), click on the arrow in its cell and then the `View` option under the `Comments` section. ![Comments/commenting on a survey response](/assets/survey-responses-comments.png) Each comment includes the date/time and the author, and comments are ordered by date/time descendingly. After a researcher comments on a response, all researchers associated with the study, except the one who commented, will receive an email notification. See [Notification Settings for Researchers](../study-setup-and-deployment/notifications.md#for-researchers) if you want to opt out from receiving such notifications. :::note You can't comment on responses that have not been stored in Avicenna yet. This includes Unanswered sessions. ::: :::note You can't edit or delete your comments after you submit them. This is intentional to preserve the integrity and transparency of the collaboration process among researchers. ::: --- sidebar_position: 1 --- # Stroop One of the Activities you can add to your study is the Stroop Test. A [Stroop Test](https://en.wikipedia.org/wiki/Stroop_effect) offers configurations that are similar to other Avicenna Activities. If you have yet to read about using Activities in an Avicenna study, we encourage you to start from [here](../activities/README.md). Like Surveys, a Stroop Test can have one or more [Triggering Logics](../activities/triggering-logics.md). They define when and how often the participant should complete the Stroop Activity. You can only use Time or User Triggering Logics with the Stroop Activity. Every time Avicenna prompts a Stroop Activity to the participant, regardless of what kind of Triggering Logics caused that prompt, a new Session is created for it. This Stroop Session stores all data related to the test. The Session may have an expiry time. In this case, the participant has a certain amount of time to complete the Stroop Activity before its Session is marked as Expired. Stroop Activities can also have [Notification Templates](../study-setup-and-deployment/notifications.md#notification-templates) to notify participants about different phases of the Activity. Also, Stroop Activities and their Triggering Logics can have Criteria. In this case, the Activity and Triggering Logics are only enabled if the Criteria is evaluated to True. You can read more about Criteria [here](../activities/criteria.md). Note that although you can assign a Criteria to a Stroop Test, the Criteria can only use Survey questions for the evaluation. You cannot use the data from a Stroop Session in your Criteria. For example, it's impossible to create a Criteria that says, "Prompt this Activity only if the Stroop Session was completed". ## Supported Stimuli The Stroop Test supports three types of stimuli: - **Congruent**: This refers to the case where the text and the font color are the same, making it easier for the brain to process and respond to the task. For example, the word "red" is in red font. - **Incongruent**: This refers to the case where the text and the font color differ, making it more difficult for the brain to process and respond to the task. For example, the word "red" is in blue font. - **Neutral**: This refers to the case where the text shown on the screen does not represent the color, making it a control condition in studies of the Stroop Effect. For example, a row of hashtags is presented in black font. These three terms are related to the Stroop Effect, a psychological phenomenon that occurs when people are asked to name the color of a word presented in a different color. | | | | | :-----------------------------------------------------------: | :---------------------------------------------------------------: | :-------------------------------------------------------: | | ![Congruent Stimulus](/assets/stroop-congruent-color-box.png) | ![Incongruent Stimulus](/assets/stroop-incongruent-color-box.png) | ![Neutral Stimulus](/assets/stroop-neutral-color-box.png) | | Congruent Stimulus | Incongruent Stimulus | Neutral Stimulus | ## Creating a New Stroop Activity To create a new Stroop Activity, open the Researcher Dashboard and navigate to the Activities page. Click on the `Create New Activity` button, and choose Stroop. This will open the Stroop Activity Editor. If you have created Surveys or other Activity types, you should know the most options in this Activity editor. For example, the Triggering Logics tab allows you to configure the Activity's Triggering Logics, or the Notification Templates tab enables you to create Notification Templates for your Activity. Below we focus on the Content section and explain the settings. ### General Settings In this section, you can set the flow of the game, its length, and the type of stimuli it should include: ![General Settings of the Stroop Activity Editor - Time Duration](/assets/cognitive-tasks-stroop-general-settings-time-duration.png) - The first setting, Duration Type, specifies whether the game should be finished after a specific time (`Time`) or a certain number of rounds (`Round`). If you choose `Time`, you must specify how long each game should be in seconds. If you choose `Round`, specify how many rounds each game should have. - You can set the Tutorial Round Count to specify how many tutorial rounds the game should have. Each Session of the game starts with the tutorial. The participant must complete the tutorial before starting the main game. - In the last part of the General Settings, you specify what stimuli you want to include in the game. You can choose from `Congruent`, `Incongruent`, and `Neutral` rounds. If your game is time-based, you can have or exclude either stimulus. Avicenna randomly generates enough rounds to fill the game duration. - If your game is round-based, you can let Avicenna randomly generate enough rounds of each stimulus to add up to the number of rounds you specified. You can also manually enter how many rounds of each stimulus you want. In this case, Avicenna guarantees that each game Session will contain that many stimuli and presents them randomly. ![General Settings of the Stroop Activity Editor - Round Duration](/assets/cognitive-tasks-stroop-general-settings-round-duration.png) For example, you can specify your game is round-based, and each participant should complete 30 rounds of the game. Then you can set that each game Session should contain 12 Congruent rounds, 12 Incongruent rounds, and six Neutral rounds. This way, for each game Session, Avicenna will generate the round types as specified (12-12-6) and present them randomly to the participant. ### Game Messages Throughout the game, Avicenna shows three messages to the participant. You can modify these messages and their translation in this section: ![Game Messages Settings of the Stroop Activity Editor](/assets/cognitive-tasks-stroop-content-game-messages.png) - The Game Introduction Message is shown on the first screen of the game immediately after the participant opens the game. This is the message they see when they start a Session of this Activity. This text cannot be longer than 500 characters. - Following the introduction page, the participant is taken to the tutorial rounds. When they complete the tutorial rounds and before they start the main game, they are shown the Pre Game Message. This text cannot be longer than 500 characters, either. - As its name implies, the Text(s) for Neutral Rounds specifies the text or texts that should be used for the Neutral stimulus rounds. In the Congruent or Incongruent rounds, Avicenna shows the color names. But for the Neutral rounds, you can enter a set of texts that will be shown randomly in each Neutral round. Each line in this text box will be considered as a separate text. Note that these texts do not have to be readable. For example, you can use `#####`. These texts (lines in the text box) cannot be longer than ten characters. - The Enforce Uniform Distribution option allows you to specify whether the texts for neutral rounds should be shown uniformly (an equal number of times) or not. This option is available only for round-based games. Also, your Stroop can't have this option enabled while there is more than one text for neutral rounds and the number of neutral rounds is either not set or not divisible by the number of texts for neutral rounds. :::note If there is zero or more than one text for neutral rounds, by default, `#####` will be used for all neutral rounds, whether it's an instruction, tutorial, or main round. ::: ### Game Layout The last set of settings in this section allows you to configure the layout of the game user interface: ![Game Layout Settings of the Stroop Activity Editor](/assets/cognitive-tasks-stroop-content-game-layout.png) - The first option, Selector Layout, allows you to choose how the choices should be shown to the participant. If you set the `Selector Layout` to `Yes/No`, the participant is asked whether the two colors are identical, and they should respond by choosing Yes or No in the game. | | | | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | ![Congruent Stimulus with Yes/No Selector](/assets/stroop-congruent-yes-no.png) | ![Incongruent Stimulus with Yes/No Selector](/assets/stroop-incongruent-yes-no.png) | ![Neutral Stimulus with Yes/No Selector](/assets/stroop-neutral-yes-no.png) | | Congruent Stimulus with Yes/No Selector | Incongruent Stimulus with Yes/No Selector | Neutral Stimulus with Yes/No Selector | If you set the `Selector Layout` to `Color Box`, the participant is shown a colored text and is asked to tap on the box with a similar color. | | | | | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | ![Congruent Stimulus with Color-Box Selector](/assets/stroop-congruent-color-box.png) | ![Incongruent Stimulus with Color-Box Selector](/assets/stroop-incongruent-color-box.png) | ![Neutral Stimulus with Color-Box Selector](/assets/stroop-neutral-color-box.png) | | Congruent Stimulus with Color-Box Selector | Incongruent Stimulus with Color-Box Selector | Neutral Stimulus with Color-Box Selector | If you set the `Selector Layout` to `Color Name`, the participant is shown a colored text and is asked to tap on the name of the color they see. | | | | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | ![Congruent Stimulus with Color-Name Selector](/assets/stroop-congruent-color-name.png) | ![Incongruent Stimulus with Color-Name Selector](/assets/stroop-incongruent-color-name.png) | ![Neutral Stimulus with Color-Name Selector](/assets/stroop-neutral-color-name.png) | | Congruent Stimulus with Color-Name Selector | Incongruent Stimulus with Color-Name Selector | Neutral Stimulus with Color-Name Selector | The next option allows you to pick what colors should be part of the game. You can choose any available combination of colors. The `Audio Feedback` and `Visual Feedback` options control whether or not the game should provide audio and visual feedback to the participant when they correctly or incorrectly respond to each round. The `Show Rounds` for round-based games, and `Show Timer` for time-based games, specify whether the timer or round counter should be shown in the game interface or not. Lastly, the `Show Score` controls whether the game should show the participants how many correct answers they have provided. ## Stroop Response Data Structure You can view the responses for your Stroop Activity in the [Kibana Integration](../analysis/kibana-basics/README.md). Each record of the data contains the following attributes: | **Name** | **Field Name** | **Type** | **Description** | | --------------------- | -------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Study ID | `study_id` | Integer | The ID of the study to which this record belongs. | | Participant ID | `user_id` | Integer | The ID of the participant who submitted this response. | | Activity ID | `activity_id` | Integer | The ID of the Stroop Activity to which this record belongs. | | Session UUID | `session_uuid` | Text (UUID) | The unique identifier of the Stroop Session to which this record belongs. | | Device ID | `device_id` | Keyword | The ID of the device on which the participant completed this Stroop Session. | | Triggering Logic ID | `tl_id` | Integer | The ID of the Triggering Logic prompted this Stroop Session. | | Triggering Logic Type | `tl_type` | Text | The type of the Triggering Logic that prompted this Stroop Session. | | Scheduled Time | `scheduled_time` | Date | For Time-Triggered Sessions shows the time the Stroop Activity was automatically triggered. For User Triggered Sessions, this shows the time the Stroop Activity was started by the participant. | | Prompt Time | `prompt_time` | Date | Same as Scheduled Time. | | Record Time | `record_time` | Date | The time the Stroop Activity was completed by the participant. | | Relative Record Time | `rel_record_time` | Date | The number of milliseconds between the participant's participation start time and the time this Session was completed. | | Session Status | `status` | Integer | The status of the Session. More [here](../activities/activity-sessions.md). | | Maximum Colored Box | `max_colored_box` | Integer | Shows the maximum number of rounds that were presented during this game Session. | | Maximum Colored Text | `max_colored_text` | Integer | Always the same as `max_colored_box`. | | Round Index | `round_index` | Integer | The index of the round that this response belongs to. | | Response Time | `resp_time` | Date | The time that this response was provided. | | Box Font Color | `box_font_color` | Text | The color of the ink that was used to write the text. | | Text Color | `text_color` | Text | The color that the text represents. For example, if the text is "Red", the text_color will be `red`. This will be `Unknown` for Neutral rounds, as the text does not represent any color. | | Question Color | `question_color` | Text | If the selector type is `Yes/No`, this represents the color text asked from participants. For `Colored Box` and `Colored Text` selectors, this value is always not defined (equals to `Unknown`). | | Neutral Round Text | `neutral_round_text` | Text | If the round is neutral, this represents the text that was shown to the participant. | | Response | `response` | Integer | If the selector type is `YES/NO`, the value is 0 for `No` and 1 for `Yes`. If the selector type is `Colored Box` or `Colored Text`, the value is the ID of the selected color, as defined in the Color IDs below. | | Response Duration | `response_duration` | Integer | The duration it took for the participant to submit this response. This value is calculated by subtracting the `resp_time` for this round index from the `resp_time` for the round index before this record. | ### Color IDs | Color Name | ID | | ---------- | --- | | Unknown | 0 | | Blue | 1 | | Yellow | 2 | | Red | 3 | | Green | 4 | | Black | 5 | ### Selector Type IDs | Selector Type | ID | | ------------- | --- | | Colored Box | 1 | | Colored Text | 2 | | Yes/No | 3 | ### Game Duration Type IDs | Duration Type | ID | | ------------- | --- | | Timed | 1 | | Round | 2 | --- sidebar_position: 2 --- # Time-Use Time-Use Activity allows your study to collect Time-Use data from participants. This Activity provides a user interface similar to a calendar and asks participants to report how they spent their time. In this calendar, participants enter what they were doing, when, where, and with whom. ![Time-Use Activity User Interface](/assets/time-use-activity-ui-completed.png) Time-Use Activity has similar configurations to other Avicenna Activities such as Stroop or Survey. A Time-Use Activity can have one or more [Triggering Logics](../activities/triggering-logics.md), but the Triggering Logics can be only of type Time or User. You cannot use other types of Triggering Logics for a Time-Use Activity. A Time TL allows participants to have access to the Time-Use Activity only at certain times, while a User TL allows the participant to access the Time-Use Activity at any time they prefer. :::info Please make sure you do not confuse the _Time Triggering Logic_ with the _Time-Use Activity_. The former refers to a Triggering Logic where the prompt time of the Activity is defined in advance based on a specific timetable. The latter is a type of Activity that asks participants to enter their Time-Use Diary in a calendar. ::: Time-Use Activities also use [Sessions](../activities/activity-sessions.md). A Time-Use Session refers to the day that the participant is requested to enter their Time-Use Diary. For example, assume you want your participants to report their Time-Use for Jan. 1st within 3 days, i.e., by Jan. 4th at the latest. You can configure your Time-Use Activity to have a Session for each participant on Jan. 1st and set it to expire on Jan. 4th. Furthermore, your Time-Use Activity may have [Notification Templates](../study-setup-and-deployment/notifications.md#notification-templates) and [Criteria](../activities/criteria.md) as well. You can use Triggering Logics and Sessions in the Time-Use Activity to achieve different study designs. Below we explain each supported design in detail, but first, let's have an overview of them. Assume that your participant joins on Monday and will be part of your study for 7 days until Sunday. Your study may ask participants for one of the following: - Complete their diary for any day within that week, as they choose. There is no requirement on which day or how many days they should fill. Or; - You may require participants to complete their diaries for Tuesday and Saturday. They may choose to complete it for other days as well, or may not. But they must complete the one weekday and one weekend you requested. Or; - You may require participants to complete their diary only for Tuesday and Saturday, and you don't want them to fill in anything for other days. We call the designated days that you request participants to fill their diary a _"Session"_, and create a [Session](../activities/activity-sessions.md) for them. The participation days that do not have a Session, we conveniently call them _"Non-Session"_ days. Time-Use Activity offers a setting, called `Allow Non-Session Completion` (or `ANSC` for brevity), which determines whether the participants should be allowed to enter data for Non-Session days as well, or not. Now using Time or User Triggering Logic, and the `ANSC` setting, you can achieve different study designs. Below we explain each study design in more detail. ## Supported Study Designs As explained above, two settings in the Time-Use Activity Editor play a key role in how the Activity behaves: - The type of Triggering Logics used for this Activity can be either _Time TL_, _User TL_, or both. - The `ANSC` option can be either `True` or `False`. The combination of 3 options for the Activity's Triggering Logics types (i.e., Time TL only, User TL only, or User and Time TL), and 2 options for the `ANSC` (True or False) gives us 6 different configurations. Of these, 3 are commonly used in Time-Use research, 1 is the byproduct of our implementation here, and 2 are not semantically meaningful and therefore Avicenna does not support it. ### Study Design 1 In the first design, we create a Time-Use Activity, add a User Triggering Logic to it, and also set the `Allow Non-Session Completion` to True. This instructs the Avicenna app with the following: 1. Participants should be able to access this Time-Use Activity at any time they choose. 2. Participants can fill out their Time-Use Diary for any day they choose. Note that participants cannot enter diary events that start more than 2 hours in the future. For example, if the current time is 2 pm, participants cannot create an event that starts at 4 pm or later. Also, participants cannot enter diary events for days prior to their participation. For example, if they joined the study on Monday, Jan. 1st, they can enter events from Jan. 1st until now, but they cannot enter diary events for Dec. 31st or earlier. Further, participants can view, modify, or delete their diary events at any time they choose. ### Study Design 2 This design is useful if you want to require participants to enter their Time-Use Diary for certain days during their participation, and at the same time allow them to enter diary events for other days if they choose to. To achieve this, you can create a Time-Use Activity, and set the `Allow Non-Session Completion` option to True. You should also add one User Triggering Logic. This instructs Avicenna to allow participants to access this Activity anytime through their app's home screen, so they can enter their diary events for any time from the start of their participation up until now. Further, you should add a Time Triggering Logic to the Activity. The Time TL should be configured such that it generates Sessions on the days that the participant is required to complete their Time-Use Diary. Lastly, you should set the Expiry Time of the Activity. This specifies how much time the participant has to report their diary events in the calendar for those required days. The expiry time is calculated from the end of the Time-Use Session. So for example, if you set the Expiry Time of your Activity to 3 days, and the Time-Use Session (the day participant is required to fill in) is on Monday, the participant has until the end of Thursday to enter her diary events for Monday. In this scenario, if there is an active Session, the app shows a button on the top part of the home screen, as shown in the left-side image below. Participants can access the Time-Use Activity by tapping on this button. If there is no active Session, e.g., if there was a Session from Monday to Thursday as in the above example, and the participant opens the app on Friday, the button for the Activity will be shown at the lower part of the home screen, as shown in the middle image. But regardless of how they open the Time-Use Activity, they will see the same set of dates and the events they entered on those dates. The Session dates are highlighted differently, as shown in the right-side image below. | | | | | :------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: | | ![Home page of the Avicenna app when there is an active Session for the participant to complete](/assets/time-use-activity-app-home-screen-active-session.png) | ![Home page of the Avicenna app when there is a Time-Use Activity with User Triggering Logic](/assets/time-use-activity-app-home-screen-user-triggering-logic.png) | ![If Allow Non-Session Completion is True, participants can fill in any days](/assets/time-use-activity-ui-allow-non-session-completion.png) | | Home page of the Avicenna app when there is an active Session for the participant to complete | Home page of the Avicenna app when there is a Time-Use Activity with User Triggering Logic | If Allow Non-Session Completion is True, participants can fill in any days | ### Study Design 3 In this study design, you ask participants to enter their diary events only for the designated days, and you do not want them to enter events for any other day. In this case, your Time-Use Activity should have only Time TL (one or more). The Time TL should be configured such that it generates the days that you want your participants to fill their Activities. Further, you should set the `Allow Non-Session Completion` to False, so when participants access the Time-Use Activity, they cannot fill in events for Non-Session days. With this design, participants see the button for opening the Time-Use Activity only when they should fill in the designated days. At other times, they cannot access the Time-Use Activity. Also, when they launch the Time-Use Activity, they only can complete the designated days. Unlike [Study Design 2](#study-design-2), they do not see a date switcher on the top of the screen. Instead, they only see the day they need to fill in, as shown in the image below. | | | | :------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![Home page of the Avicenna app when there is an active Session for the participant to complete](/assets/time-use-activity-app-home-screen-active-session.png) | ![If Allow Non-Session Completion is False, participants can fill in only the designated days](/assets/time-use-activity-ui-not-allow-non-session-completion.png) | | Home page of the Avicenna app when there is an active Session for the participant to complete | If Allow Non-Session Completion is False, participants can fill in only the designated days | ### Study Design 4 A less common use of Time-Use Activity is by setting the `Allow Non-Session Completion` to True while adding only a Time TL to the Activity. Enabling the `ANSC` setting in Avicenna lets participants freely choose any day for logging their diary events when they open the Time-Use Activity (as long as it's not in the future). At the same time, because the Time-Use Activity only has Time TL, it can only be accessed by the participants on the dates that the Time TL instructs. So this means participants can see and open the Time-Use Activity on certain designated days, but when they do open it, they can use the day selector on the top of the calendar interface to enter diary events for any dates. ### Unsupported Configuration Avicenna Time-Use Activity does not support cases where the `Allow Non-Session Completion` is set to False, and the Activity also has a User Triggering Logic. That's because setting the `ANSC` option to False instructs Avicenna to prevent participants from completing Non-Session days, while adding a "User TL" instructs the app to allow participants to have access to the Time-Use Activity during Non-Session days as well. These two settings are contradictory and therefore Avicenna does not support them. ## Session Status If your Time-Use Activity includes a Time Triggering Logic, Avicenna creates one or more Sessions for it. Each Session refers to a day that you expect the participant to enter their Time-Use data. As you have read in the definition of the [Activity Sessions](../activities/activity-sessions.md) in Avicenna, each Session has a status. For the Time-Use Activity, the status value is defined as follows. A Time-Use Session status is set to `Unknown` immediately after it's created. This means the Session is created and is waiting for the participant to complete it, but it's not known yet whether the participant completes it or not. Here, we define a _completed Time-Use Session_ as a Session where the participant enters enough diary events to fill in a certain percentage of the day, more than a certain number of diary events, or both. You can set the `Minimum Completion Percentage` and `Minimum Event Count` settings in your Time-Use Activity to specify when Avicenna should consider a Session as `Completed`. If you set both of these values to 0, Avicenna marks the Session as `Completed` when the expiry time of the Session is reached. If you set the `Minimum Completion Percentage` to a certain value such as X%, the participant should report events covering a minimum of X% of their day for the Session to be considered complete. Similarly, if you set `Minimum Event Count` to Y events, the participant should enter a minimum of Y diary events for that day for the Session to be considered `Completed`. If the expiry time of the Session is reached and the participant has not entered a minimum of Y events or has not reported events for X% of their day, the Session will be marked as `Expired`. ### Completed Status Evaluation In Activities such as Surveys, when the participant completes the Activity, Avicenna marks it as completed, and does not show that Activity on the app's homepage anymore. This is because participants cannot make changes to an already completed Activity, and therefore there is no need to have access to it either. Time-Use Sessions work differently. Participants have access to these Sessions, even after they are completed until their _Expiry Time_ arrives. This allows the participant to open the calendar and enter more diary events if they choose to. For example, assume your study has a Time-Use Activity and is configured such that the Sessions for it are marked as completed if the participant covers 80% of their day, and reports a minimum of 10 diary events. Alice joins your study and receives the Session to report her Time-Use Diary. She enters 12 diary events, one by one, and covers 75% of her day. When she enters the 13th diary event, the system detects she meets the criteria for the Time-Use Session to be marked as completed. That's because she has entered 13 events (more than 10), and has covered 85% of her day (more than 80%). In this case, Avicenna marks Alice's Time-Use Session as completed. But unlike other Activities, it allows Alice to continue making changes to the Session by adding, modifying, or removing diary events. In the above example, as Alice continues changing her Time-Use Diary, the status of the Time-Use Session can transition from _Unknown_ (the default status) to _Completed_ and back multiple times. This is unlike Sessions from other Activities, where the Session status does not change when it's marked as _Completed_. --- sidebar_position: 3 --- # Page Page Activity allows you to display an HTML web page to the participants via the Avicenna app. You can create the page via any tool you prefer, for example, by using common weblog services or by programming it and hosting it on your local server. The page can contain any information you want to present to your participants via the app. The only requirement is that the page must have a public URL (e.g., [https://avicennaresearch.com](https://avicennaresearch.com)) and be hosted on a secure website, i.e., the URL should start with https. Like other Activities such as Surveys, Page Activity can also have [Triggering Logics](../activities/triggering-logics.md), though only User TLs are supported. You cannot add Triggering Logics other than User TL to your Page Activity. There is no [Session](../terminology.md#session) defined for Page Activity, and you cannot define any [Notification Templates](../study-setup-and-deployment/notifications.md#notification-templates) for them either. You can, however, set a [Criteria](../activities/criteria.md) on a Page Activity or its Triggering Logics. To add a new Page Activity to your study, go to the Researcher Dashboard, navigate to the Activities page, click on `Create New Activity`, and choose `Page`. After creating such activity, you will be then directed to the Page Activity Editor, as shown in the following image: ![Page Activity Editor](/assets/page-activity-editor.png) There is only one option you can set for the Page Activity, and that's the URL you want to display when the participant launches this Activity. After setting the URL, add a User TL to your Activity, and then set any Criteria if necessary. Then you can publish your Activity and try it in the Avicenna app. In the Avicenna app, participants will always have access to the button to launch this Activity and view the specified web page. Similar to other Activities, the icon and the caption of this Activity are the same as what you have specified in the Page Activity Editor. Clicking on this button will show the web page directly in the Avicenna app. | | | | :---------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------: | | ![Homepage of the Avicenna app with a Page Activity](/assets/page-activity-app-home-screen.png) | ![Avicenna app shows the specified URL to the participant.](/assets/page-activity-app-launched.png) | | Homepage of the Avicenna app with a Page Activity | Avicenna app shows the specified URL to the participant | The app is designed to open this URL inside the app and doesn't take the participant to an external browser. Furthermore, to ensure the participant has a seamless experience, the components of the Page Activity viewer are kept to the minimum, So you can design your web page to appear as an integral part of the main application. This allows you to extend the app's functionality by adding dynamic content to it. ## Placeholders You can use placeholders in the URL of a Page activity to show different web pages to different participants based on their context. The placeholders are replaced with the actual values when the participant opens the Page activity. Currently, we support only one placeholder: `{{participant_id}}`. As the name suggests, this refers to the participant's ID. ## Troubleshooting ### The page refuses to connect on the participant web app and Preview This issue is likely due to the `X-Frame-Options` header or Content Security Policy (CSP) settings on the web server hosting the page. Many websites set these security headers to prevent their content from being embedded in `iframe`s on other domains, which is how the Avicenna web app displays Page activities.
![Page activity refused to connect](/assets/page-activity-refused-to-connect.png)
In Chrome, for example, you might see an error message like `www.example.com refused to connect`. Other browsers may show similar messages.
To resolve this, you'll need to modify the web server configuration to allow the page to be embedded within Avicenna. Here are some common solutions: 1. Set the `X-Frame-Options` header to `ALLOW-FROM https://avicennaresearch.com`. However, the `ALLOW-FROM uri` directive from the `X-Frame-Options` header is now considered deprecated and is not supported by all browsers. 2. Or use a more modern header: `Content-Security-Policy: frame-ancestors 'self' https://avicennaresearch.com` If you don't have direct access to the server configuration, contact your web administrator or hosting provider for assistance in implementing these changes. We assumed you are the owner of the page. --- sidebar_position: 4 --- # Working Memory Updating A Working Memory Updating (WMU) task tests participants' ability to hold and manipulate numbers in their [working memory](https://en.wikipedia.org/wiki/Working_memory). Participants view a set of numbers and perform arithmetic operations on them mentally, continuously updating the results as new operations appear. This cognitive task offers configurations similar to other Avicenna activities. If you have yet to read about using activities in an Avicenna study, we encourage you to start from [here](../activities/README.md). WMU tasks can have one or more [triggering logics](../activities/triggering-logics.md). They define when and how often the participant should complete the WMU activity. You can only use Time or User triggering logics with the WMU activity. Every time Avicenna prompts a WMU activity to the participant, regardless of what kind of triggering logic caused that prompt, a new session is created for it. This WMU session stores all data related to the task. The session may have an expiry time. In this case, the participant has a certain amount of time to complete the WMU activity before its session is marked as Expired. WMU activities can also have [notification templates](../study-setup-and-deployment/notifications.md#notification-templates) to notify participants about different phases of the activity. Also, WMU activities and their triggering logics can have criteria. In this case, the activity and triggering logics are only enabled if the criteria is evaluated to True. You can read more about criteria [here](../activities/criteria.md). ## Task Flow The WMU task consists of these phases: 1. **Introduction**: Participants see an introduction page. ![Introduction page](/assets/cognitive-tasks-wmu-introduction-page.png) 2. **Initial Numbers**: Four cells appear, each containing a random integer number between 0 and 9 (inclusive). ![Initial numbers page](/assets/cognitive-tasks-wmu-initial-numbers-page.png) 3. **Updating Operations**: Five random operations appear, one at a time. Each operation applies to one of the four cells randomly, and no two consecutive operations are applied to the same cell. Operations are either addition or subtraction and the amount is between 1 and 8 (inclusive). Updating operations won't result in the intermediate or final results being less than 0 or greater than 9. ![Updating operation example](/assets/cognitive-tasks-wmu-updating-operation-example.png) 4. **Respond**: Participants enter their calculated final numbers for all four cells based on the initial numbers and the corresponding updating operations. They can skip responding to any cell. After moving on to the next cell (either by clicking on Next or simply because the maximum time per response is reached), the participant can't go back to the previous cell. ![Respond page](/assets/cognitive-tasks-wmu-respond-page.png) :::note On iOS devices, the participant can only respond to the cells by tapping on them. This is because the default keyboard doesn't show up automatically when the cells are focused. On the other hand, Android devices will show the default keyboard when the cells are focused. ::: :::info As you see in the screenshot above, a thin progress bar will be shown under the Next and Submit (used for the last cell) buttons so participants know how much time they have left to enter their response in the current cell while not getting distracted too much. ::: 5. **Results**: Participants see the correctness of their responses with green and red colors. ![Results page](/assets/cognitive-tasks-wmu-results-page.png) ## Creating a New WMU Activity To create a new WMU activity, open the researcher dashboard and navigate to the `Activities` page. Click on the `Create New Activity` button, and choose `Working Memory Updating`. This will open the WMU activity editor. If you have created other activity types, you should know most options in this activity editor. Below we focus on the `Content` section and explain the settings specific to WMU. ![WMU activity editor settings](/assets/cognitive-tasks-wmu-general-settings.png) - **Introduction Message**: Enter a message (up to 1000 characters) that participants will see on the introduction page. This can be translated if your study is multilingual. If you skip it, a default message will be shown. - **Initial Numbers Duration**: Set how long (in milliseconds) participants should see the initial four numbers. - **Update Operation Duration**: Set how long (in milliseconds) each updating operation must be shown. - **Blank Page Duration**: Set the duration (in milliseconds) of blank pages/cells between the initial numbers page, the updating operation pages, and the participant response page. - **Maximum Time Per Response**: Set the maximum time (in milliseconds) allowed for responding to each cell. ## Responses Similar to other types of activities, you can view, filter, and export responses to your WMU activity in the `Activity Responses` page of your researcher dashboard. Besides the columns and other functionalities of the data filtering shared between all activities, the WMU responses have the following columns: ![WMU responses](/assets/cognitive-tasks-wmu-responses-page.png) - **Initial Numbers**: The four initial numbers shown to the participant. - **Updating Operations**: The sequence of updating operations, including cell index and operation. - **Responses**: The participant's final answers for each cell. - **Expected Responses** - **Percentage of Correct Responses** For more information on how to view and filter your data, see [Data Filtering](../study-setup-and-deployment/data-filtering.md). --- sidebar_position: 1 --- import SampleDataButton from '@site/src/components/sample-data-button'; # Raw Data ## Exporting Raw Data You can use Researcher Dashboard to export data collected from data sources or activity responses. Both data sources and activity responses support export as CSV, though you have more options depending on the type of the data being exported. For example, for GPS you may also choose `KML` or `GPX` export, or for contact network data you may also choose to export as `GEXF`. To export your data, open the researcher dashboard and navigate to the `Data Export` page: ![Data Export page in Avicenna Researcher Dashboard](/assets/data-export-page.png) In this page, you start with choosing the list of participants for whom you want to export the data, and the type of data you want to export. Depending the type of data, Avicenna may ask you to choose the export format as well. For most data sources, you can download the data as a CSV file. Although for GPS you can also choose `KML` or `GPX`, and for Bluetooth Beacons you can choose `GEXF` as well. After selecting the export format, you can choose the date range as well. Pressing `Export` will start the data export process. The export may take up to a few hours to complete, depending on the size of the data. You can always come back this page to check the status of your data export. When the data export file is ready, you will receive an email about it, and you can come back to the _Data Export_ file to download the file. Note that the _Data Export_ page will also list all Survey Response export requests, even though for exporting the survey responses you need to use the _Responses_ page, as explained in the [View Responses document](../../reference/surveys/view-responses.md). Each data export will be available for download for up to 7 days. After that, Avicenna automatically deletes the export file. If you need to download the data again, you must create a new data export. At the moment Avicenna does not have any limitations on the size of the data export file. But for sensor data this file can be very large, specially if a long date range and many participants are chosen to be exported. So it's not uncommon for the file to surpass 10GB in size. There is no limitation at the moment on the file size, though we do request that if you expect your data export to be very large, break it into multiple requests, so it can generate multiple files. ### Data Fields The data fields you will find in each file depend on the type of data being exported. For survey responses, the list of available fields are explained in the [View Responses](../../reference/surveys/view-responses.md#survey-data-structure) document. For the sensor-based data sources, the list of data sources are described in their related section in the [Data Sources document](../../reference/data-sources/). ## Downloading Record Counts You can download a CSV file containing the count of the collected records in each hour-long interval grouped by data source for each participant in the study. This provides a quick overview of the data collection volume across different data sources in your study. To do that, on the `Data Export` page, click on `Download All Data Sources Record Counts as CSV`. The downloaded CSV file includes the following columns: - `data_source_id`: The unique identifier for the data source. See the [Data Source ID Reference](#data-source-id-reference) for more details. - `user_id`: The participant's unique identifier. - `participant_type`: Either ["Main" or "Test"](../study-setup-and-deployment/enrollment.md#participant-type). - `device_id`: The unique identifier of the device that collected the data. - `time_bin`: The date and hour for which the aggregated count is reported. - `count`: The number of records collected for that data source on that date. ### Data Source ID Reference The following table provides a reference for mapping data source IDs to their corresponding data sources: | ID | Data Source | | --- | ---------------------------------- | | 1 | Accelerometer | | 2 | Ambient Temperature | | 3 | Gyroscope | | 4 | Gravity | | 5 | Light | | 6 | Linear Acceleration | | 7 | Magnetic Field | | 8 | Orientation | | 9 | Pressure | | 10 | Proximity | | 11 | Relative Humidity | | 13 | WiFi | | 14 | Bluetooth | | 15 | GPS | | 16 | Battery | | 19 | Ambient Audio | | 20 | App Usage (Legacy) | | 24 | Screen State | | 25 | Pedometer | | 26 | Activity Recognition | | 27 | Bluetooth Beacon | | 30 | Fitbit Heart Rate | | 33 | Fitbit Sleep | | 37 | Garmin Health | | 39 | HealthKit | | 42 | Garmin Health Daily | | 43 | Garmin Health Heart | | 44 | Garmin Health Respiration | | 45 | Garmin Health Sleep Daily | | 46 | Garmin Health Sleep | | 47 | Fitbit Activity Summary | | 48 | Garmin Health Pulse Ox | | 49 | Garmin Health Stress | | 50 | Garmin Health Body Composition | | 51 | Garmin Health User Metrics | | 52 | Weather | | 53 | Fitbit Activity | | 54 | Fitbit Sleep Level | | 55 | Fitbit Active Zone | | 58 | WHOOP Workout | | 59 | WHOOP Sleep | | 60 | WHOOP Recovery | | 61 | Polar Exercise | | 62 | Polar Sleep | | 63 | Polar Continuous Heart Rate | | 64 | Polar SleepWise Circadian Bedtime | | 65 | Polar SleepWise Alertness | | 66 | Fitbit Weight Log | | 67 | SensorKit Heart Rate | | 68 | SensorKit Accelerometer | | 69 | SensorKit Rotation Rate | | 70 | SensorKit Ambient Light | | 71 | SensorKit Ambient Pressure | | 72 | SensorKit Device Usage Report | | 73 | SensorKit Keyboard Metrics | | 74 | SensorKit Message Usage Report | | 75 | SensorKit On Wrist State | | 76 | SensorKit Pedometer | | 77 | SensorKit Phone Usage Report | | 78 | SensorKit Telephony Speech Metrics | | 79 | SensorKit Siri Speech Metrics | | 80 | SensorKit Visits | | 81 | SensorKit Wrist Temperature | | 82 | Hexoskin Shirt | | 98 | HealthKit Activity | | 99 | HealthKit Vital Signs | | 100 | HealthKit Sleep Analysis | | 103 | HealthKit State of Mind | | 105 | Web Activity Tracking | ## Direct Database Access While Avicenna's data export allows you to create complex queries and export any data from your study as CSV, this will not cover all analysis cases. For more advanced use-cases, you may need to connect directly to the database. We can provide direct database access to your team to query and work with your study data. At the moment, this feature is not automatically provided. If you need to have direct database access, please contact [Avicenna Support](mailto:support@avicennaresearch.com). ## Handling of Timezones Every piece of information stored in Avicenna is time-stamped as appropriate. All time values are stored internally in UTC. However, keep in mind that all participants' data exported from your study will be based on the participants' timezones. This is because presenting participants' data in their local timezones enhances researchers' ability to interpret and analyze the data accurately, aligning it with the study protocol and the participants' context. ## Troubleshooting ### I see extra lines in the exported CSV files When working with the exported CSV files (e.g., survey responses), cell values with line breaks may appear as extra lines in some text editors. The CSV format handles this by enclosing such content in double quotes (`"`). Most data analysis tools (e.g., Excel, Google Sheets, R, Python) correctly interpret these quoted fields. Try importing the CSV into a spreadsheet application like Google Sheets and see if the issue persists. # Kibana Basics ## Avicenna Kibana Integration [Kibana](https://en.wikipedia.org/wiki/Kibana) is an open-source data visualization tool which can create different graphs and charts from large amounts of data. Kibana allows you to explore the data, create visualizations such as bar chart, line charts, scatter plots, maps, and many more. You can further combine these visualizations to create interactive dashboards. In this document, we describe how you can use Kibana to explore and visualize your Avicenna study data. This document does not intend to teach you how Kibana, Elasticsearch, or Lucine works. There are already many online resources and training videos for these technologies. We suggest you review them to better understand how you can use Kibana for your work. For each study you create in Avicenna, a set of data tables are created in a data storage system called [Elasticsearch](https://en.wikipedia.org/wiki/Elasticsearch). These tables are also called _index_ or _index pattern_. Kibana allows you to access these data tables, query them, read the data, and visualize them. To access the Kibana, go to the Researcher Dashboard, and from the left-side menu click on _Kibana_. This will take you to a page similar to the image below: ![Kibana first page](/assets/kibana-first-page.png) There are 4 important sections in the above image: Number `1` lists the data tables for your study. Your study does not necessarily have data in all these tables, depending on which [data sources](../../data-sources/README.md) and which [activities](../../activities/) you have added to your study. Number `2` shows the time range over which you are querying the data. By default, the time range just shows the data for the past 15 minutes, so there is a chance that you do not see any data. You can increase this time range to load more data. Number `3` lists the data fields that are available in the current data table. This list is different depending on the data table that you have selected. For example, for GPS it includes the location and the speed of the movement, while for Pedometer it includes the number of steps taken. Number `4` allows you to filter your data. You can put filter on any data field that exist in the current data table. For example, assuming that you are looking at the Pedometer data table, you can filter data for those who have taken 100 steps or more. :::info By clicking on the `Share` button at the top, you can export your data. ::: Avicenna does not store all data sources in the Elasticsearch. At the moment, only the following data sources are stored in the Elasticsearch and therefore are accessible through Kibana: - GPS (`gps` index) - Wi-Fi (`wifi` index) - Pedometer (`pedometer` index) - Motion-based Activity Recognition (`mb_activity_rec` index) - Battery (`battery` index) - Screen State (`screen_state` index) - Bluetooth (`bluetooth` index) - Bluetooth Beacons (`beacon` index) - App Usage Statistics (`app_uage` index) - Call & SMS logs (`telephonycomms` index) - Participant Audit Logs (`participant_history` index) - Survey Responses (`survey_responses` index) - Stroop Responses (`stroop_responses` index) - Time Use Diary Responses (`time_use_responses` index) - Fitbit Activity Summary (`fitbit_daily_activity` index) - Fitbit Activity Intraday (`fitbit_activity` index) - Fitbit Sleep (`fitbit_sleep` index) - Fitbit Heart Rate (`fitbit_heart_rate` index) - WHOOP Sleep (`whoop_sleep` index) - WHOOP Workout (`whoop_workout` index) - WHOOP Recovery (`whoop_recovery` index) Below you can read the details for each of these data sources, including available fields and their types. Avicenna clusters host the services for Kibana and Elasticsearch. Therefore, your study data does not leave Avicenna servers for any of the procedures described here. ## Available Data Sources This section describes the available data sources and the fields each data source have in Kibana. The name of the field is necessary to access the field's data in Kibana. The field's type specifies the type of the data being stored in it. You can refer to [Elasticsearch's field datatypes](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html) for more details about each type. You also can check the [Data Sources](../../data-sources/README.md) section for detailed definition of each field. ### Common Fields The following data fields are available in each of the data sources described below: | **Name** | **Field Name** | **Type** | **Description** | | -------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Study ID | `study_id` | Integer | The ID of the study this record belongs to. | | Participant ID | `user_id` | Integer | The ID of the participant who provided this record. | | Device ID | `device_id` | Keyword | The ID of the device which provided this record. Each participant can own multiple devices during the course of the study, and each device will have a unique ID. Avicenna uses this ID to tag all records coming from the same device. The ID remains the same even when the user uninstalls and reinstalls the Avicenna app on their phone. | | Record Time | `record_time` | Date | The time which this record was captured. For survey responses, `record_time` for all responses in the same session are identical, and it represents the time when the user has pressed Submit button (or equivalent) to finish responding to the survey. | | Relative Record Time | `rel_record_time` | Date | The number of milliseconds between the participant's participation period start time, and the time this record was captured. This field is particularly useful for studies with rolling enrollment, where each participant starts the study at a potentially different date. Therefore, 0 indicates the record was captured right at the start time, 1 indicates the record was captured 1 ms after the start time, and so on. Note that this field is marked as Date, therefore Avicenna will show the field as milliseconds passed [Unix epoch](https://en.wikipedia.org/wiki/Unix_time) (Jan. 1st, 1970). If you plan to query the data based on this field, you need to set the time range based on this date. | ### Survey Responses For survey responses, Avicenna stores each response to a given question as a separate record. Therefore, a given survey session can contain multiple records. For example, assume your survey contains 5 questions, from question ID 1 to 5. Every time a participant responds to your survey, 5 new records will be added to this index, one for each question (assuming the participant has responded to all questions). Also, note that not each record contains all the fields specified here. If a given record does not have a given field, it means the field was not relevant for that record. For example, if a survey response is of type text, the record will contain `answer_content`, but it will not contain `answer_url`. **Index name:** `survey_responses` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ----------------- | ---------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Survey ID | `survey_id` | Integer | | | Question Set ID | `questionset_id` | Integer | | | Response Duration | `duration` | integer | In minutes. | | Scheduled Time | `scheduled_time` | Date | For Time- and Proximity-Triggered sessions, this shows the time the survey was automatically triggered. For User Triggered sessions, this shows the time the survey was started by the participant. | | Prompt Time | `prompt_time` | Date | Same as Scheduled Time. | | Response Time | `resp_time` | Date | The time this response was provided. | | Iteration | `iteration` | Integer | | | Loop Count | `loop_count` | Integer | | | Question ID | `q_id` | Integer | | | Question Content | `q_content` | Text | | | Question Type | `q_type` | Keyword | | | Answer ID | `answer_id` | Integer | | | Answer Content | `answer_content` | Text | | | Answer URL | `answer_url` | Keyword | | | Location | `location` | Geo Point | | | Location Accuracy | `location_accu` | Double | | | Location Speed | `location_speed` | Double | | | Preferred Unit | `pref_unit` | Keyword | | | Selector | `selector` | Keyword | | ### Device State The `Device State` logs are utilized to convey various states and settings of participants' Android and iOS devices running the Avicenna native app. They provide a holistic view of the device's operational status, covering aspects from battery life to connectivity. New reports are created as soon as one of the fields changes its value. For example, if the power saving mode is enabled, a new report is created that includes the new value of the power saving mode field and the latest values of other fields. **Index name:** `device_state` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ------------------------ | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Battery Status | `battery_status` | Keyword | A battery level below 15% is considered `LOW`.
**Values**: `UNKNOWN = 0`, `OK = 1`, `LOW = 2` | | Battery Level | `battery_level` | Integer | Shows the current battery level as a percentage (0-100%). The app will check for updates on this field if any other field changes (not upon battery level changes). | | Power Saving Mode | `power_saving_mode` | Keyword | **Values**: `UNKNOWN = 0`, `Enabled = 1`, `Disabled = 2` | | Battery Optimization | `battery_optimization` | Keyword | Android only.
**Values**: `UNKNOWN = 0`, `Enabled = 1`, `Disabled = 2` | | Power Connectivity | `is_power_connected` | Keyword | Indicates whether the device is currently connected to a power source.
**Values**: `UNKNOWN = 0`, `Enabled = 1`, `Disabled = 2` | | Storage Status | `storage_status` | Keyword | Android only. Provides information about the device's internal storage status. `OK` and `LOW` values depend on the device's specifications and system reports.
**Values**: `UNKNOWN = 0`, `OK = 1`, `LOW = 2` | | Memory Status | `memory_status` | Keyword | Android only. Reports the status of the device's RAM usage. Avicenna checks the memory status every 15 minutes alongside the OS notifications regarding low memory conditions. `OK` and `LOW` values depend on the device's specifications and system reports.
**Values**: `UNKNOWN = 0`, `OK = 1`, `LOW = 2` | | Network Connection type | `network_connection_type` | Keyword | **Values**: `UNKNOWN = 0`, `NOT_CONNECTED = 1`, `CELLULAR = 2`, `WIFI = 3` | | Airplane Mode | `airplane_mode` | Keyword | Android only.
**Values**: `UNKNOWN = 0`, `Enabled = 1`, `Disabled = 2` | | Do Not Disturb Mode | `do_not_disturb` | Keyword | Android only.
**Values**: `UNKNOWN = 0`, `Enabled = 1`, `Disabled = 2` | | Locale | `locale` | Keyword | | | Time Zone | `timezone` | Keyword | | | Operating System Version | `os_version` | Keyword | | :::info After the participant logs in to the Avicenna native app on their iOS and Android devices, all fields will be initialized with their current state **one by one**, and each initialization will generate a new log. Until these fields get updated with their actual initial state, their value will be `UNKNOWN` in the logs. ::: ### Application State The `Application State` logs report various states and settings of participants' Android and iOS apps. They provide a holistic view of the application's status. New reports are created as soon as one of the fields changes its value. For example, if the app language changes, a new report is created that includes the new value of the language field and the latest values of other fields. **Index name:** `application_state` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | --------------------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Email Notifications | `email_notifications` | Keyword | Indicates whether email notifications are enabled or disabled in the application settings.
**Values**: `UNKNOWN`, `ENABLED`, `DISABLED` | | SMS Notifications | `sms_notifications` | Keyword | Indicates whether SMS notifications are enabled or disabled in the application settings.
**Values**: `UNKNOWN`, `ENABLED`, `DISABLED` | | Wi-Fi Only Upload | `wifi_only_upload` | Keyword | Specifies whether data uploads are restricted to Wi-Fi connections only in the application settings.
**Values**: `UNKNOWN`, `ENABLED`, `DISABLED` | | Allow Data Collection | `allow_data_collection` | Keyword | Denotes whether data collection is permitted by the participant in the application settings.
**Values**: `UNKNOWN`, `ENABLED`, `DISABLED` | | Language | `language` | Keyword | The current language of the application set by the participant. | | App Version Number | `app_version_number` | Integer | The current version number of the application. | | Execution Mode | `exec_mode` | Keyword | Indicates the execution mode of the application.
**Values**: `UNKNOWN`, `BACKGROUND`, `FOREGROUND`, `TERMINATED` (only iOS supports this value and it will be logged only when the participant, not the OS, terminates the app) | | Execution Mode Change Occurred At | `exec_mode_change_occured_at` | Date | Timestamp of the last time the execution mode has changed. | | Onboarding Alerts | `onboarding_alerts` | Nested | A list indicating changes in alerts related to app permissions and settings that may require user attention or action. Each alert is defined with a `type` (see the next tables) and `status` (**Values**: `UNKNOWN`, `Added` which means the alert showed up on the app, `Deleted` which means the alert was taken care of by the participant in some way). | | Study Data Sources | `study_datasources` | Nested | A list indicating whether data sources are enabled/disabled. Each data source is defined with a `type` (see the next tables) and `status` (**Values**: `UNKNOWN`, `Enabled`, `Disabled`). | | Survey Notifications | `survey_notifications` | Keyword | Android only. Indicates the status of survey notifications.
**Values**: `UNKNOWN`, `ENABLED`, `DISABLED` | | Sticky Notifications | `sticky_notifications` | Keyword | Android only. Indicates the status of sticky notifications.
**Values**: `UNKNOWN`, `ENABLED`, `DISABLED` | :::info After the participant logs in to the Avicenna native app on their iOS and Android devices, all fields will be initialized with their current state **one by one**, and each initialization will generate a new log. Until these fields get updated with their actual initial state, their value will be `UNKNOWN` in the logs. ::: | **Onboarding Alerts Types** | **Description** | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Unknown | | | GPS | To grant the app permission to collect GPS data. Also, on iOS devices, with GPS permission, Avicenna can keep the app open in the background for a longer time. | | Activity Recognition | To grant the app permission to collect motion sensor data. | | App Usage | To grant the app permission to collect app usage data. | | Bluetooth | To turn the Bluetooth on. | | WiFi | To turn the WiFi on. | | Garmin | To grant Avicenna permission to access Garmin data. | | Fitbit | To grant Avicenna permission to access Fitbit data. | | WHOOP | To grant Avicenna permission to access WHOOP data. | | HealthKit | iOS only. To grant Avicenna permission to access HealthKit data. | | SensorKit | iOS only. To grant Avicenna permission to access Sensor data. | | Audio Capture | To grant the app permission to record audio from the microphone. | | Background App Refresh | iOS only. To enable background app refresh. | | Time-Sensitive Notification | iOS only. To enable time-sensitive notifications. | | Persistent Notification Banner | iOS only. To enable the persistent notification banner. | | Phone Validation | To verify the phone number. | | Email Validation | To verify the email address. | | Application Update | To notify when a new app version is available on the store. | | Location Service | To enable the Location service. | | Notifications | To grant the app permission to prompt notifications. | | Battery Optimization | Android only. To disable battery optimization. | | Battery Optimization (Device Specific) | Android only. To disable battery optimization if the device is "Sony", "Samsung", "Huawei", "Xiaomi", or "Oneplus". | | Schedule Alerts | Android only. To grant the app permission to schedule notifications and alarms. | | **Study Data Sources Types** | | --------------------------------- | | Unknown | | Accelerometer | | Ambient Temperature | | Gyroscope | | Gravity | | Light | | Linear Accelerometer | | Magnet | | Orientation | | Pressure | | Proximity | | Relative Humidity | | WiFi | | Bluetooth | | GPS | | Battery | | Ambient Noise | | Ambient Audio | | App Usage | | Screen State | | Pedometer | | Motion Based Activity Recognition | | Beacon | | Apple HealthKit | | Apple SensorKit | | Fitbit | | Garmin | | WHOOP | ### GPS **Index name:** `gps` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | -------------- | ---------------- | --------- | --------------- | | Provider | `provider` | Keyword | | | Satellite Time | `satellite_time` | Date | | | Location | `location` | Geo Point | | | Speed | `speed` | Double | | | Accuracy | `accu` | Double | | | Altitude | `alt` | Double | | | Bearing | `bearing` | Double | | ### Wi-Fi **Index name:** `wifi` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ------------------------- | -------------- | -------- | --------------- | | SSID | `ssid` | Keyword | | | BSSID | `bssid` | Keyword | | | Access Point Capabilities | `capabilities` | Keyword | | | Frequency | `freq` | Integer | | | Level | `level` | Integer | | ### Pedometer **Index name:** `pedometer` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ------------------- | ----------------- | -------- | --------------- | | Steps | `steps` | Integer | | | Accuracy | `accu` | Double | | | Distance | `distance` | Double | | | Average Active Pace | `avg_active_pace` | Double | | | Current Cadence | `cur_cadence` | Double | | | Current Pace | `cur_pace` | Double | | | Duration | `duration` | Integer | | | Floor Ascended | `floor_ascended` | Double | | | Floor Descended | `floor_descended` | Double | | ### Motion-based Activity Recognition **Index name:** `mb_activity_rec` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ---------------- | ------------------ | -------- | --------------- | | Activity Type | `activity_type` | Integer | | | Confidence Level | `confidence_level` | Integer | | ### Battery **Index name:** `battery` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ----------- | -------------- | -------- | --------------- | | Level | `level` | Integer | | | Scale | `scale` | Integer | | | Status | `status` | Integer | | | Plugged | `plugged` | Integer | | | Temperature | `temperature` | Integer | | | Voltage | `voltage` | Integer | | ### Screen State **Index name:** `screen_state` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ------------ | -------------- | -------- | --------------- | | Screen State | `state` | Boolean | | | End Time | `end_time` | Date | | ### Bluetooth **Index name:** `bluetooth` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ------------ | -------------- | -------- | --------------- | | MAC Address | `mac` | Keyword | | | Device Name | `dev_name` | Keyword | | | Device Class | `dev_class` | Keyword | | | RSSI | `rssi` | Integer | | ### Bluetooth Beacons **Index name:** `beacon` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | ------------ | -------------- | -------- | --------------- | | MAC Address | `mac` | Keyword | | | Device Name | `dev_name` | Keyword | | | Device Class | `dev_class` | Integer | | | Payload | `payload` | Long | | | Team ID | `team_id` | Integer | | | Role ID | `role_id` | Integer | | | Subject ID | `subject_id` | Integer | | | RSSI | `rssi` | Integer | | ### App Usage **Index name:** `app_usage` **Index fields (see [Common Fields](#common-fields) too):** | **Name** | **Field Name** | **Type** | **Description** | | --------------- | -------------------- | -------- | ---------------- | | App Name | `app_name` | Keyword | | | Start Time | `start_time` | Date | | | End Time | `end_time` | Date | | | Last Used | `last_used` | Date | | | Foreground Time | `foreground_time_ms` | Integer | In milliseconds. | ## Troubleshooting ### I can't log in to Kibana If you're seeing an "Invalid username or password" error when trying to access Kibana, try these steps: 1. **Access Kibana through the researcher dashboard**. Instead of going directly to the Kibana URL, first log in to the researcher dashboard, then click on the Kibana button from the sidebar menu. This should automatically authenticate you. 2. **Clear browser cookies**. If the above doesn't work, try clearing all cookies related to the `avicennaresearch.com` domain in your browser, then log in to the researcher dashboard again and access Kibana from there. 3. **Log out and log back in**. Sometimes logging out of the researcher dashboard completely and logging back in before clicking the Kibana button can resolve authentication issues. ### Date/time values in Kibana seem off by a few hours When viewing date/time values in Kibana, you may notice some of those values appear off by a few hours from what you expect, while some others are always in UTC (e.g., the date/time values in [the Message field under the Audit Trail](../../study-setup-and-deployment/audit-trail.md#message)). That's because Kibana guesses the browser's timezone and adjusts the standalone UTC date/time fields to that timezone. Note that [Avicenna stores almost all date/time values in UTC](../../study-setup-and-deployment/participation-period.md#time-zone), but the Kibana configuration may change those to your local timezone. To resolve this issue, you can do one of the following: - Export the data via the researcher dashboard and analyze it in third-party software. - Use a browser extension to force the UTC timezone. This ensures consistency between Kibana's date/time fields and text-based fields that may contain date/time values (e.g., Audit Trail's Message). Also, if you want to use the participant's local timezone, you can still use a browser extension to force that timezone, but note that: - Text-based fields that may contain date/time values won't automatically align with the timezone you set, and - You'll need to cross-reference [the audit logs for timezone change events](../../study-setup-and-deployment/audit-trail.md#30-timezone-changed) and manually adjust time zones for periods between those events. --- sidebar_position: 1 --- # Data Quantity in Kibana ## Plot Data Quantity using Kibana In this article, we describe how you use Kibana to monitor the number of data records each participant uploads during a certain time period. If you are not familiar with how Kibana works with Avicenna, you can read the [Kibana Basics](./) page first and then continue here. Start by opening Kibana from your Researcher Dashboard. Now from the left panel, go to the _Visualize_ tab, click on the `Create Visualization` button and from the list choose _Heat Map_ visualization. In the dialog that opens, search for the data index you want to use. Here, we want to use the Pedometer data, so we search for it in the list: ![Choose data source for the Kibana Heatmap Visualization](/assets/kibana-viz-heatmap-choose-data-source.png) After selecting the data source, a graph is shown based on the default parameters. We need to adjust these parameters using the left-side panel: | | | :----------------------------------------------------------------------------------------: | | ![Kibana Heatmap Visualization Options](/assets/kibana-viz-heatmap-pedometer-settings.png) | In the Data tab, in the _Metrics_ section, expand the `Value Count` and ensure the _Aggregation_ is set to _Count_ (the default option). This specifies that for each cell of our heat map (or for each bucket, as called in Kibana), we want to count the number of records in that bucket and plot the aggregate result. If you are not familiar with how metrics and buckets work in Elasticsearch and Kibana, [this 10-minute video](https://www.youtube.com/watch?v=j-eCKDhj-Os) is a good introduction. Then we need to define our buckets. For this example, we want to show user IDs in the X-Axis and dates on the Y-Axis. We can define that in the _Buckets_ section. Click on the `+` icon, choose _X-Axis_, from the _Aggregations_ list select _Terms_, and set the _Field_ to `user_id`. You can specify the order of the data by setting the _Order By_ field. The last field is the _Size_. You can use _Size_ to specify how many user IDs to be returned. Here I set it to 20. | | | :-------------------------------------------------------------------------------: | | ![Kibana Heatmap Visualization Options](/assets/kibana-viz-heatmap-options-2.png) | To specify the _Y-Axis_, click on `+` again, and choose _Y-Axis_. We want to aggregate the data per date. So choose _Date Histogram_ and set the Field value to `record_time`. Also, set the interval to _Daily_, so the plot will show aggregate data over date. When done, click on the `Update` button on the bottom right corner of the panel to apply the changes. | | | :-------------------------------------------------------------------------------: | | ![Kibana Heatmap Visualization Options](/assets/kibana-viz-heatmap-options-3.png) | Also, don't forget to select a time window from the top right corner of the page. By default, it's set to show the data from the last 15 minutes. But for most cases, there is not enough data to plot and you will get an empty graph. Here I set the time range to the past 15 weeks instead: ![Kibana Data Quantity Heatmap](/assets/kibana-viz-heatmap-result.png) As I only had one participant in my study, the X access has only one item. You can move the cursor on the graph, and for each cell you can see the date, the user ID, and the number of records that user has provided on that date. You can also use filters to put criteria on the records which are being counted. This filter can be based on any field in the data. Obviously, you can filter data to include or exclude specific users. Moreover, as we are using GPS data here, you can filter data based on a specific geo-region, or the speed. To do that, simply click on the `Add a filter` on the top left corner of the screen, and you can define your filter. ### Special Case: Survey Responses The above example counts the number of records stored in Kibana for each user for each date. This generates a valid data quantity report for all data sources in Avicenna, except Survey Responses. As we [explained before](./#survey-responses), Avicenna stores response to each question as a separate record. So if a survey has 10 questions and the user responds to 8 of them, Avicenna will store 8 separate records for that session, one per response. Each record contains 5 date fields: `scheduled_time`, `issued_time`, `record_time`, `rel_record_time`, and `resp_time`. You can read more about each of these fields [here](./#survey-responses). Except `resp_time`, all other 4 fields are identical for all responses to a specific session. So in the example above, all 8 responses will contain identical values for `scheduled_time`, `issued_time`, `record_time`, and `rel_record_time`. So if you want to count the number of survey sessions per participant per day, all configuration remains the same as above, except the metric. For metric, you need to use you need to set the metric to Unique Count of one of the 4 date values, as shown below. | | | :---------------------------------------------------------------------------------------: | | ![Configuration for Plotting Survey Responses](/assets/kibana-viz-heatmap-for-survey.png) | | Configuration for Plotting Survey Responses | --- sidebar_position: 2 --- # Proximity Survey in Kibana ## Proximity Survey Plot Via Avicenna, you can use Bluetooth beacon devices to capture participant's interaction with real-world elements, and subsequently trigger surveys based on these interactions. While this is a very powerful feature, monitoring its operation can be very challenging, as there are many dynamic elements involved. We [previously described](../../data-sources/from-smartphone/contact-network.md#designing-beacon-based-studies) how you can design and implement a study using Bluetooth beacons. In this article, we focus on how you can monitor the beacon data reported by a given participant, and the surveys triggered by Avicenna based on those captured beacon data. The graphs plotted here can be very valuable to monitor a small part of the study in details, and ensure beacon capture and associated survey triggering is done as expected. ## Study Design In this study, we want to capture participant's interactions with three distinct elements: 1. The amount of time they spend with their alter. In this study, alter is not enrolled in the study as a participant, so she does not have Avicenna app, nor she necessarily has a phone. 2. The amount of time they spend at their office. 3. The amount of time they spend in their car. While for #2 and #3 we could use GPS data as well, in this study we decided to use Bluetooth beacons. Beacon data are more reliable particularly when indoors, and also their data does not raise privacy concerns in participants as much as GPS data. So for our scenario here, Bluetooth beacons are a good alternative to using GPS. For this example, assume we only have 1 participant, who together with their associates form one team: Team #1. In that team, we have 4 roles: participant, alter, office room, and car. We assign an ID to each role as follow: - Participant: Role #1 - Alter: Role #2 - Office room: Role #3 - Car: Role #4 Lastly, as we only have 1 subject for each of those roles in our only team, their subject ID for each will be 1. The following table shows the Team, Role, and Subject ID for each element of our study: | | Team ID | Role ID | Subject ID | | ----------- | ------- | ------- | ---------- | | Participant | 1 | 1 | 1 | | Alter | 1 | 2 | 1 | | Office Room | 1 | 3 | 1 | | Car | 1 | 4 | 1 | If we had multiple participants, each participant would form a separate team with their unique team ID, while the role and subject ID in those team would remain as above. ## Configuring Beacons Now that we have defined the required Team/Role/Subject ID for each element of our study, we can start configuring a beacon for each. As we need to capture participant's interaction with the other elements (alter, office, & car), and not the other way around, we do not need to ask the participant to also carry a Bluetooth beacon. If the participant was also expected to periodically announce their presence to their potential team members, we would need to allocate them a beacon as well. But that is not the case here. We start by entering the information of all beacons and participants we have in the `Beacon Mapping` section of the _Participation_ page. [Here](../../data-sources/from-smartphone/contact-network.md#beacon-mapping-page) you can learn more about the specifics of this page. At the end, our page setting should look like the following image: ![Configuring Beacons in the Beacon Mapping Page](/assets/kibana-beacon-vis-beacon-mapping.png) ## Surveys For this study, we also define 3 surveys: first when they meet their alter, second when they arrive at the office, and the third when they leave their car. For each of these surveys, you should define a [proximity triggering logic](../../activities/triggering-logics#proximity-tl) with the following settings: - Teams: Only from members of teams with the same team ID as current user. - Roles: Trigger this survey only if a contact has been detected between the following roles: - From `1` to `2` - Trigger Prompt: Trigger this survey after visiting the subject for 0 minutes continuously. - Prompt Interval: 60 minutes apart. This triggering logic specifies a survey should be triggered when two beacons from the same team meet, where one is from Role # 1 (the participant) and the other one is from Role #2 (the alter). Also, the survey should be triggered immediately after they meet, and should not be triggered for another hour following each trigger. Assume the ID for this survey is 2064. The second logic is for arriving at the office: - Teams: Only from members of teams with the same team ID as current user. - Roles: Trigger this survey only if a contact has been detected between the following roles: - From `1` to `3` - Trigger Prompt: Trigger this survey after visiting the subject for 120 minutes continuously. This specifies the survey should be triggered when a participant (Role #1) arrives at the office (Role #3). The survey should be triggered when the participant stays in the office for 2 hours. Assume the ID of this survey is 2070. The third trigger is for when the user leaves the car (i.e., finishes driving): - Teams: Only from members of teams with the same team ID as current user. - Roles: Trigger this survey only if a contact has been detected between the following roles: - From `1` to `4` - Trigger Prompt: Trigger this survey 30 minutes after departing. - Prompt Interval: 0 minutes apart. This triggering logic specifies that the survey should be prompted 30 minutes after the participant (Role #1) departs from the car (Role #4). Assume the ID of this survey is 2071. ## Tracking Data Collection and Survey Prompts In this section, we discuss how we can monitor the beacon data captured by the Avicenna app, and the related triggered surveys. We start by dividing the incoming data into six categories, based on the related role, and triggered surveys: - Beacon data representing the participant visiting the alter (i.e., the alter's s beacon). - The times when survey 2064 is prompted (as it's related to visiting the alter). - Beacon data representing the participant staying in the office. - The times when survey 2070 is prompted. - Beacon data representing the participant driving the car. - The times when survey 2071 is prompted. We will use Kibana to create a timeline graph for each of these data and combine them into a dashboard. The resulting dashboard should clearly show when the participant visits or departs from each of the roles in her team, and how the related surveys are prompted. Note that the details of setting up Kibana is described in [another article](./). If you need more details about how to follow the steps described here, please check that article. We need to create one visualization for each of the six graphs described above. Let's start creating the first by clicking on the `Create visualization` button. From the list, pick `Timelion`. This graph will represent the number of times our participant's Android app has visited the alter's beacon. The related Timelion Expression will be as follow: ``` .es(index=beacon, timefield=record_time, q="study_id:380 AND user_id:1 AND team_id:1 AND role_id:2").label("Participant 1 -> Alter") ``` This query specified that it should work on the data from index `beacon`, and it should use `record_time` as the time field. The `q` parameter allows us to filter the beacon data and only retrieve the ones we need. We query the data using the following fields: - `study_id:380` only retries the data for our study with ID 380. - `user_id:1` only retrieves the data reported by Avicenna participant ID 1. Note that this ID is not the same as Subject ID we assigned above. This ID is usually 4 digits longs, and assigned to the participant automatically by Avicenna when they create their account. - `team_id:1` allows us to filter the data further and from all beacon data reported by participant #1, report the ones where the Team ID of the observed beacon was 1. - `role_id:2` further filters the data to those where the role ID of the observed beacon was 2. Therefore, the query above fetches the data reported by Participant (User) ID #1, where she/he visited a beacon with Team ID 1 and Role ID 1. We do not filter data based on Subject ID here, as we only have 1 subject per Role per Team. For more details on each field discussed here, you can refer to the Bluetooth Beacon's [reference document.](../../data-sources/from-smartphone/contact-network.md#bluetooth-beacons) Also, the resulting time series graph should be labeled as `Participant 1 -> Alter`. Note that the `user_id` specified above refers to the Avicenna participant ID which is usually 4 or more digits long, and not the subject ID you have assigned to the user. Finally click on the `Update` button to plot the time series. Your final time series visualization should look like the following, although as we have no data collected yet, our graph is flat, but your data will show the record counts assuming it contains data: ![First Timelion Graph in Kibana Showing Bluetooth Beacon Data](/assets/kibana-beacon-vis-timelion-first.png) Now save your visualization as `Study 380 - Visiting Alter`. When done, go back to the Visualization page to create the second graph. The second graph is to plot the when and how many times study 2064 is prompted to the participant ID 1. Follow the same steps as above to create a Timelion visualization, but this time, use the following Timelion Expression: ``` .es(index=survey_responses, timefield=scheduled_time, q="study_id:380 AND user_id:1 AND survey_id:2064", metric=cardinality:scheduled_time).label("#2064 - Visit Alter - No Expiry - Offset 0 - Min Consecutive : 1 hour ") ``` This expression specifies that the data should be taken from index `survey_responses`, with `scheduled_time` as the time field. Note that here we are not using `record_time`, as we are interested in the time the survey was prompted (`scheduled_time`), and not the time the survey was responded by the participant (`record_time`). The other difference in this query is that we specify we want to plot the cardinality of the `scheduled_time`. By default, Timelion plots the total number of records available. As Avicenna creates a separate record for each question in a given survey, if the prompted survey has for example 8 questions when the participant responds to the survey once, 8 distinct records will be created, all having the identical `scheduled_time`. So here we specify the plot should be using cardinality of the `scheduled_time` (distinct values of this field). When done, your plot should look like this: ![Second Timelion Graph in Kibana Showing Survey Resonses Data](/assets/kibana-beacon-vis-timelion-second.png) Save this graph as `Study 380 - Survey Meet Alter` and go back to the Visualizations tab. Follow the above steps for the other 4 plots as well. The Timelion Expression and the saved name for each plot are included below: ``` Name: Study 380 - Visiting Office Timelion Expression: .es(index=beacon, timefield=record_time, q="study_id:380 AND user_id:1 AND team_id:1 AND role_id:3").label("User 1 -> Office") Name: Study 380 - Survey Arrive Office Timelion Expression: .es(index=survey_responses, timefield=scheduled_time, q="study_id:380 AND user_id:1 AND survey_id:2070", metric=cardinality:scheduled_time).label("#2070: Arrive Office - No Expiry - Arrival - 2 hours") Name: Study 380 - Visiting Car Timelion Expression: .es(index=beacon, timefield=record_time, q="study_id:380 AND user_id:1 AND team_id:1 AND role_id:4").label("User 1 -> Work") Name: Study 380 - Survey Depart Car Timelion Expression: .es(index=survey_responses, timefield=scheduled_time, q="study_id:380 AND user_id:1 AND survey_id:2071", metric=cardinality:scheduled_time).label("#2071: Depart Car - No Expiry - Departure - 30 min") ``` When done creating a visualization for each of the graphs we discussed above, we need to create a dashboard and put all these visualizations together. To do so, click on the `Dashboard` icon on the left panel, and then click on `Create a Dashboard`. Add each visualization to the dashboard by clicking on `Add` from the top of the page, and selecting each of the visualizations we created one by one. --- sidebar_position: 8 --- # Security and Compliance At Avicenna Research Inc., keeping our systems and data secure is a top priority. We have built a solid foundation of security practices over the years by putting together a combination of ongoing efforts and new measures to ensure our systems and data are well-protected. More importantly, in November 2024, we made improvements to meet [the ISO 27001:2022 certification](#meeting-iso-standards) requirements. Here is an overview of what we are doing to stay secure. ## Brief Non-Technical Summary For those who may not be familiar with technical terms, here's a quick overview of our security measures: - We keep our systems updated regularly to protect against vulnerabilities. - Our monitoring systems are always on the alert for potential security issues. - We ensure that access to our systems is secure and monitored. - Our compliance with international standards and frameworks like ISO, HIPAA, and GDPR ensures that we follow best practices in data security and privacy. ## Meeting ISO Standards We are proud to have achieved [ISO 27001:2022 certification through UKAS](https://certcheck.ukas.com/certified-entity/adc99141-1f0e-5832-951d-c9b4c1682be7). This shows that our security practices meet international standards and that we are committed to keeping things secure. ## Meeting GDPR Standards As a data processor, Avicenna does comply with GDPR and currently, multiple European institutions have Data Controller and Data Processor agreements with Avicenna in place. Below we explain how our privacy policy and overall system architecture are set to comply with GDPR requirements. 1. GDPR does apply to Avicenna, as a data processor. 2. Participant unambiguous consent Our software will require each study to have a consent form. As explained in section 6.2. of our [Privacy Policy](https://avicennaresearch.com/legal), the consent form is required to "... specify, among other things, (1) what is the purpose of the study (2) what are the potentials risks or benefits to you as the Participant (3) what type of data is being collected (each referred to as a Data Source) (4) how the data will be handled and who will have access to the data (5) how you can contact the Researcher (6) what is the withdrawal process." This consent form will be presented to participants before joining a study, and they have to agree to this before being able to participate. The consent form is available to the participants throughout the study participation. 3. Further processing outside of what mentioned in the consent form Avicenna does not perform any processing on the data collected for a given study. 4. Participants' right to access their data Avicenna provides each participant with an online account. The credentials of that account are the same as the ones used to sign up in the Avicenna app. Participants can log in to their online account on Avicenna's website at any time to access their data. 5. Participant's right to delete their data Avicenna allows participants to delete all or part of their data directly through their online account (as described in Section 10.6 of the [Privacy Policy](https://avicennaresearch.com/legal#privacy-policy)). If the participant does not have enough technical skills to use this option, they can contact our support for assistance. 6. Data Portability Participants in any Avicenna study can contact Avicenna's Support team and ask for a copy of their data. We will provide them with a machine-readable file containing all data collected from them. 7. Data Storage and flow Avicenna stores all data on servers physically located in Canada. All Avicenna employees and support staff are also located in Canada, therefore the data does not flow to any country other than Canada. Canada is considered by the EU Data Protection Commission [as a country that provides adequate data protection](https://ec.europa.eu/info/law/law-topic/data-protection_en). You can find more information in [Avicenna's Privacy Policy and Terms of Use](https://avicennaresearch.com/legal). For example, Section 6.5. _Data Sources We May Collect From the Participant, While Enrolled in a Study_, talks about different data sources, the anonymization methods that can be used for each, and the potential concerns for each. Or Section 6.6 _Data Encryption, Upload, Storage, and Anonymization_, talks about how Avicenna encrypts, uploads, and stores the data. If you have any questions regarding this topic, please feel free to [email us](mailto:support@avicennaresearch.com). ## Detailed Security and Compliance Practices ### Keeping Systems Updated We update all operating systems and software monthly. This includes on-premise servers running **Rocky Linux 9.x**, AWS-based EC2 instances, and critical internal services like: - Firmware - Hypervisor (Proxmox) - Source Code Management and CI/CD Pipelines (Gitlab) - Chat (Mattermost) - Ticketing System (Zammad) - IAM (Keycloak) - LDAP (Authentik) - Firewalls - Vulnerability Manager (Greenbone Vulnerability Manager - GVM) - DAST (ZAP) - SIEM (Wazuh) - Databases (PostgreSQL, Elasticsearch, Cassandra) - OS and Programming Languages' Packages and Libraries - Reverse Proxies (OpenResty, Nginx) - Web-Application Firewall (OPNSense) ### Finding and Fixing Vulnerabilities We run vulnerability checks monthly and after each deployment to ensure the security of our systems. These vulnerabilities are addressed according to our internal timelines: - Operating system vulnerabilities - Network vulnerabilities - Dynamic Application Security Testing (DAST) ### Monitoring for Security Issues Our Security Information and Event Management system, powered by Wazuh, helps us monitor security problems in real time. It includes: - Alerts for potential security threats - Anti-malware, anti-virus, and anti-rootkit detection - File integrity monitoring to catch unauthorized changes - Collection and analysis of logs from various applications, including databases, reverse proxies, operating systems, and AWS, to ensure comprehensive security monitoring ### Keeping an Eye on System Health We use Prometheus, Grafana, and exporters to monitor how our systems are performing. This includes: - Detailed metrics for operating systems, databases, and applications - Detailed metrics of our system and the business logic - Alerts to notify us if something goes wrong or crosses a threshold ### Securing The Development Process To make sure our software is safe, we have built security checks into our development pipelines: - **Static Application Security Testing (SAST)**: Finds vulnerabilities in our code and packages/libraries. - **Dynamic Application Security Testing (DAST)**: Scans our running apps to catch security issues. - Regular linting and style checks ensure clean and consistent code. ### Managing Access Securely We have integrated Identity & Access Management across all systems to manage access securely. This makes it easier to control who can access what. ### Protecting The Network Our network is protected with: - A unified firewall setup using OPNSense, Proxmox firewall, and Linux firewall - Suricata for intrusion detection and prevention which helps us monitor and block unauthorized traffic ### Preventing Malware All our servers are protected with anti-virus software to guard against malware. ### Risk Management and Incident Handling We have established processes to identify and manage potential risks: - We regularly assess and prioritize risks to promptly address the most critical ones. - Our incident response plan outlines clear steps for handling security incidents, including identification, containment, eradication, recovery, and lessons learned. - We conduct regular training for our team to ensure they are prepared to respond effectively to any security incidents. ## How to Get in Touch If you have any security concerns or need to report an issue, you can contact us at [support@avicennaresearch.com](mailto:support@avicennaresearch.com). # How-To Articles Here you will find a collection of articles that will help you get the most out of Avicenna's platform and features. Whether you are new to Avicenna or an experienced user, these articles will provide you with step-by-step instructions and best practices for using Avicenna effectively. Each article here focuses on a specific task, and provides step-by-step instruction on how to achieve this task in your research study. ## Study Setup - [Define Participant Variables](../how-to/study-setup/define-participant-variables.md) - [Enroll Participants Without Asking for any Personally Identifiable Information](../how-to/study-setup/enroll-participants-without-asking-for-any-personally-identifiable-information) - [Randomize Participants for Multi-Arm Studies](../how-to/study-setup/randomize-participants-for-multi-arm-studies.mdx) ## Activities - [A Richer VAS Question How to Use Images as Labels](../how-to/activities/a-richer-vas-question-how-to-use-images-as-labels) - [Add an "Other" Option to Single Answer or Multiple Answer Questions](../how-to/activities/add-an-other-option-to-single-answer-or-multiple-answer-questions) - [Edit Surveys During the Study](../how-to/activities/edit-surveys-during-the-study) - [Enable Triggering Logic Only for One Participant](../how-to/activities/enable-triggering-logic-only-for-one-participant) - [How to Create a Baseline Survey in Avicenna](../how-to/activities/how-to-create-a-baseline-survey-in-avicenna) - [How to Create a One Time Optional Survey](../how-to/activities/how-to-create-a-one-time-optional-survey) - [How to Set Reminders Based on Participants Preferences](../how-to/activities/how-to-set-reminders-based-on-participants-preferences) - [Monitor Participants' Past Compliance and Upcoming Survey Schedule](../how-to/activities/monitor-participants-past-compliance-and-upcoming-survey-schedule) - [Personalized Surveys in Avicenna](../how-to/activities/personalized-surveys-in-avicenna) - [Prompt a Survey More Than Once a Day](../how-to/activities/prompt-a-survey-more-than-once-a-day) - [Schedule Sessions with Customized Timing for Each Participant](../how-to/activities/schedule-sessions-with-customized-timing-for-each-participant) ## Analysis - [Making Sense of Your Surveys Exported Data](../how-to/analysis/making-sense-of-your-surveys-exported-data) We hope you find these articles helpful and informative. If you have any questions or feedback, or if you have suggestion for new articles, please don't hesitate to reach out to our support team at [support@avicennaresearch.com](mailto:support@avicennaresearch.com). --- title: Study Setup sidebar_position: 1 --- # Study Setup How-To Articles This section contains How-To articles related to setting up and deploying your study: - [Define Participant Variables](define-participant-variables.md) - [Enroll Participants Without Asking for any Personally Identifiable Information](enroll-participants-without-asking-for-any-personally-identifiable-information) - [Randomize Participants for Multi-Arm Studies](randomize-participants-for-multi-arm-studies.mdx) # Define Participant Variables This guide explains how to assign custom data, or variables, to individual participants in your Avicenna study. ## The Situation You need to store specific information for each participant that isn't collected through regular surveys. This information, set by you (the researcher), can then customize the participant's experience. Common use cases include: - Assigning participants to different study arms (e.g., `Control`, `Intervention`). - Showing different content in surveys based on participant data. - Importing existing participant data from other sources into Avicenna. Avicenna uses [_Researcher-Responded Surveys_](../../reference/activities/triggering-logics.md#researcher-responded-tl) to manage these participant variables. ## What to Do? Follow this recipe to define, set, and use participant variables: 1. **Create** a new survey solely for variables. Name it clearly, e.g., `Participant Variables`. - **Delete** any default questions and triggering logics. - **Do not add** any triggering logic. This survey is _only_ for researcher input. ![Survey for defining participant variables](/assets/participant-variables-survey.png) 2. **Add** one question for each variable you need. - For variables with a single value (like study arm), use a _single-answer_ question. - Example: Label the question `Arm`. Set the content to `Participant's study arm?`. - **Define** answer options (e.g., `Control`, `Intervention`). Consider making it `Mandatory`. - _(For variables holding multiple values, you might use section loops. See [Survey Flow Control](../../reference/surveys/flow-control.md#looping-through-a-section).)_ !["Participant Variables" survey's arm question](/assets/participant-variables-survey-arm-question.png) 3. **Save and Publish** the `Participant Variables` survey. - **Ignore** warnings about missing triggering logic. This is expected. ![Publishing the "Participant Variables" survey](/assets/participant-variables-publish-survey.png) 4. **(Optional) Set up** notifications for `Participant Joined` events. - This helps you promptly set variables for new participants. ![Notification template for "Participant Joined"](/assets/notification-template-participant-joined-researcher-recipient-email-medium.png) 5. **Navigate** to `Activity Sessions` when ready to set variables for a participant. - **Click** `Submit New Session`. - **Select** the `Participant Variables` survey and the target participant. - **Click** `Next`. ![Create a new session for the "Participant Variables" survey](/assets/participant-variables-create-new-session-for-variables-survey.png) 6. **Fill out** the survey with the correct variable values for that participant. - **Submit** the session. ![Respond to the "Participant Variables" survey](/assets/participant-variables-respond-to-variables-survey.png) 7. **Use** the variables in your study design. - Reference them in activity [Criteria](../../reference/activities/criteria.md) to control logic. - Display them using [Placeholders](../../reference/surveys/questions.md#placeholders) in surveys or notifications. ## Pro Tips ### Editing Variables You have two options. Choose one and use it consistently. 1. **(Recommended)** Find the participant's _original_ `Participant Variables` session in `Activity Sessions`. Use filters or the `Go to Join Time` button. Click the session, then `Edit Responses`, modify, and submit. ![Edit the responses to the "Participant Variables" survey](/assets/participant-variables-edit-variables.png) 2. **Submit** a _new_ `Participant Variables` session for the same participant. Avicenna always uses the _latest_ session's data for criteria and placeholders. Older sessions remain but are inactive. ### Bulk Setting For many participants, setting variables manually is slow. [Contact support](mailto:support@avicennaresearch.com) about bulk updates (e.g., via CSV). Fees may apply. Ensure the `Participant Variables` survey structure is defined first. # Enroll Participants Without Asking for any Personally Identifiable Information When enrolling a new participant in your Avicenna Study, they are required to sign up for an account by providing the following information: - First name - Last name - Email address - Password The first two (names) are optional, but the email address and password are mandatory. The participant will use these credentials every time they want to access the app. However, since the email address is considered personally identifiable information, you may not want to ask participants to enter their email addresses to join the study. The solution is simple: you can create a catch-all email address, use it to generate a unique email address for each participant, and ask them to sign up using the provided email address. To do so: 1. Assume you have a study in Avicenna called `My Fitness Pal`. 2. Go to Gmail, and create an email account as `myfitnesspalstudy@gmail.com`. 3. Assign a unique code to each of your participants, for example, `p01` to `p20`. 4. The email addresses for each participant will be from `myfitnesspalstudy+p01@gmail.com` to `myfitnesspalstudy+p20@gmail.com`. 5. Now, you have a unique email address for each participant in your study. 6. Share the email addresses with your participants and ask them to sign up and enroll in your study. They need to choose a password for their account. ![](/assets/signup-without-identifiable-information.png) This method works because, in Gmail, any text coming after the `+` sign in an email address is skipped. So all email addresses from `myfitnesspalstudy+p01@gmail.com` to `myfitnesspalstudy+p20@gmail.com` will be aliases for `myfitnesspalstudy@gmail.com`. :::warning Using this method, any email Avicenna sends to the participant emails (such as password resets or notifications) will be received by your study's main email address. ::: :::note You can further limit enrollment in your study to only the accounts you created. Check [here](../../reference/study-setup-and-deployment/enrollment.md#invitation-based) for more details. ::: :::note While this method works for Gmail, most other mail servers also offer a similar feature. ::: import SideBySide from '@site/src/components/side-by-side'; # Randomize Participants for Multi-Arm Studies Randomized Controlled Trials (RCTs) are crucial in clinical research. This guide shows two ways to randomly assign participants to different study arms or groups within Avicenna, even though it's not a built-in feature yet. ## The Situation You are running an RCT and need to randomize participants into different arms (e.g., control vs. intervention). Avicenna currently lacks a dedicated randomization feature. You need a workaround to achieve this randomization directly within the platform or by integrating an external process. :::info Alternative Use Case The methods described here can also generate a random value as a survey response for other purposes. ::: ## What to Do? Here are two approaches to randomize participants: ### Approach 1: Using a Single Study This approach uses features within one Avicenna study to assign groups. It supports **Simple** randomization but not complex techniques like **Block** or **Stratified**. Learn more about randomization types [here](https://pmc.ncbi.nlm.nih.gov/articles/PMC2267325/). You can implement this using either survey questions or participant variables. #### Option 1.1: Using Survey Questions 1. **Create a baseline survey:** This survey will capture the participant's assigned group. See [How to Create a Baseline Survey](../activities/how-to-create-a-baseline-survey-in-avicenna.md). 2. **Add a single-answer question:** Use a [single-answer question](../../reference/surveys/questions.md#single-answer) to represent the group assignment. Avoid [number questions](../../reference/surveys/questions.md#number) as some numbers might be chosen more often than others intuitively. 3. **Configure for two arms:** - **Set question content:** Write `Choose one.` - **Define answer options:** Enter identical text (e.g., `A` or spaces) for both options to avoid bias. Note which answer ID corresponds to which arm. You can also use [image answers](../../reference/surveys/questions#answers-properties). - **Enable randomization:** Turn on `Randomize Answer Order` for the question. ![Asking participants to choose one of two visually identical options](/assets/participant-randomization-asking-participant-two-arms.png) 4. **Configure for more than two arms:** - **Set question content:** Write `Choose the option below.` - **Define answer options:** Use identical text (e.g., `A` or spaces) for all options. Remember the ID-to-arm mapping. [Image answers](../../reference/surveys/questions#answers-properties) are also possible. - **Enable randomization:** Turn on `Answer Randomization`. Select all answer IDs for `Included Answer ID(s)` and set `Selection Count` to `1`. ![Asking participants to choose one option when only one is displayed randomly](/assets/participant-randomization-asking-participant-three-arms.png) 5. **Label the question:** Use a clear label, like `Arm`. 6. **Make it mandatory:** Mark the question as `Mandatory`. 7. **(Optional) Add more questions:** Include other necessary baseline questions in the survey. 8. **Use the group in criteria:** Apply the `Arm` question's response in [criteria](../../reference/activities/criteria.md) for activities, triggering logics, or notification templates to customize the experience per arm. Using this question as a [placeholder](../../reference/surveys/questions.md#placeholders) is not recommended as it shows identical text. 9. **Participant experience:** When participants join, they complete the baseline survey. They will see either two identical options (for two arms) or one randomly selected option (for more than two arms) to determine their group. Participant view for two-arm randomization Participant view for three-arm randomization #### Option 1.2: Using Participant Variables 1. **Define a participant variable:** Treat the participant's arm/group as a variable. [Define and set this variable](define-participant-variables.md) when a participant joins. 2. **Assign the variable value:** You can either: - **Randomize externally:** Perform randomization outside Avicenna (e.g., using a spreadsheet) and set the variable for each participant accordingly. - **Randomize internally:** Use the survey method described in [Option 1.1](#option-11-using-survey-questions) to determine the group and set the variable based on the response. This has the same limitations regarding randomization techniques. :::note Limitation of This Approach The first approach (using one study) works best if your study arms differ only in their [activities](../../reference/activities/README.md) and [notification templates](../../reference/study-setup-and-deployment/notifications.md#notification-templates), not in aspects like [data sources](../../reference/data-sources/README.md). ::: ### Approach 2: Using Multiple Studies This approach involves creating a separate study for each arm. 1. **Create studies per arm:** Set up distinct studies for each arm (e.g., "Control Study", "Intervention Study"). See [Create a New Study](../../reference/study-setup-and-deployment/create-a-new-study.md). 2. **Use identical consent forms:** Ensure all studies use the same [Consent Materials](../../reference/study-setup-and-deployment/create-a-new-study#consent-materials). This prevents participants from noticing differences if they have study IDs or [registration URLs](../../reference/study-setup-and-deployment/enrollment#using-registration-url). 3. **Randomize externally:** Assign participants to arms outside Avicenna (e.g., using spreadsheet randomization). 4. **Enroll participants:** Direct participants to [join the study](../../reference/study-setup-and-deployment/enrollment#study-enrollment) corresponding to their assigned arm, or [invite them via email](../../reference/study-setup-and-deployment/enrollment#invite-participants). :::caution Maintainability Using multiple studies means duplicating the study setup. Common protocols require repetitive implementation. Mid-study changes must be applied across all study copies, though some tools might help [streamline this](../../faq.md#how-can-i-rapidly-deploy-similar-studies-with-minor-differences). ::: ## Pro Tips **Blinding Considerations:** - **Single-blinded studies:** Where participants are unaware of their group, the approaches described work well. - **Double-blinded studies:** Where researchers also shouldn't know group assignments, use these approaches but restrict access to data revealing group allocation (like baseline survey responses). Manage this using [Roles and Permissions](../../reference/study-setup-and-deployment/roles-and-permissions.md). Choose the approach that best fits your study's complexity and operational workflow. --- title: Activities sidebar_position: 2 --- # Activities How-To Articles This section contains How-To articles on setting up surveys and cognitive tasks for your study, and configuring them to fit your study protocol. - [A Richer VAS Question How to Use Images as Labels](a-richer-vas-question-how-to-use-images-as-labels) - [Add an "Other" Option to Single Answer or Multiple Answer Questions](add-an-other-option-to-single-answer-or-multiple-answer-questions) - [Edit Surveys During the Study](edit-surveys-during-the-study) - [Enable Triggering Logic Only for One Participant](enable-triggering-logic-only-for-one-participant) - [How to create a baseline Survey in Avicenna](how-to-create-a-baseline-survey-in-avicenna) - [How to Create a One Time Optional Survey](how-to-create-a-one-time-optional-survey) - [How to Set Reminders Based on Participants Preferences](how-to-set-reminders-based-on-participants-preferences) - [Monitor Participants' Past Compliance and Upcoming Survey Schedule](monitor-participants-past-compliance-and-upcoming-survey-schedule) - [Personalized Surveys in Avicenna](personalized-surveys-in-avicenna) - [Prompt a Survey More Than Once a Day](prompt-a-survey-more-than-once-a-day) - [Schedule Sessions with Customized Timing for Each Participant](schedule-sessions-with-customized-timing-for-each-participant) --- sidebar_position: 2 --- # Monitor Participants' Past Compliance and Upcoming Survey Schedule In this article, we demonstrate how you can use Avicenna to monitor your participants' compliance rate for the past activities, and the schedule of the upcoming ones. Checking this report regularly is very important while the study is in the field, as it will help you to uncover potential issues, and ensure the quality of the incoming data meets your expectations. To see the report for your study's past sessions you need to: 1. Go to the **Researcher Dashboard** -> **Sessions**. 2. Choose your study from the top section of the new page. 3. Select the **Participants** and the **Activities** that you wish to get the report for. 4. Choose your target period. ![Selecting Participants, Activities, and the target Period](/assets/how-to-activity-monitor-survey-sessions-select-participants-activities-period.png) 5. Tap **Apply Filters** to see the report for the selected options. ## Making Sense of the Report Once you receive the session status report, depending on whether you chose "Day", "Week", "Month", or "Year", you are shown a calendar with a few cells in some days. Each cell represents an activity session, and contains the following information: - The ID of the activity - The status of the session - The time the activity was scheduled for - The time the activity was concluded (completed, expired, canceled, etc.) For different statuses a given activity session can have, please check the [Activity Sessions](../../reference/activities/activity-sessions.md) page of the Reference documentation. ![Session Cell Components](/assets/how-to-activity-monitor-survey-sessions-cell-details.png) If you click on each cell, a dialog will open which contains more derails for the selected session: ![Details Survey Session Dialog](/assets/how-to-activity-monitor-survey-sessions-cell-detail-dialog.png) --- sidebar_position: 3 --- # Enable Triggering Logic Only for One Participant Assume you have a survey in your study, `Survey A`, with one triggering logic. Your study also has 10 participants. You want the triggering logic to be enabled for Participant number 2 and be disabled for all other 9 participants. :::note Here we explain how to enable a triggering logic for one specific participant, but you can apply the same concept for any subset of participants. This same concept also applies to enabling a survey or any other activity type in Avicenna. ::: There are two ways to do so. Below we explain each method. ## Method One: Asking Participants to Enter a Code. In this method, the idea is you share a random code with each participant (e.g. `321`), ask participants to enter their code when they join the study, and enable the triggering logic for participants with the desired code. ### 1. Assign a Code to Each Participant & Ask for Code Upon Enrollment 1. Create a Baseline Survey for your study (explained [here](./how-to-create-a-baseline-survey-in-avicenna.md)). This survey will be prompted immediately after the participant enrolls in your study. 2. Add a Number question to your Baseline Survey with the following content: `Please enter the code provided to you by the researcher.` ![Baseline Survey](/assets/baseline-survey.png) 3. `Save` and `Publish` your Baseline Survey. ### 2. Enable Triggering Logic Only for Participants with the Desired Code 4. Open `Survey A` for editing. 5. From the top right, click on the `Triggering Logics`. 6. Select the triggering logic type you want to set for the participant. 7. Click `Edit` to open the triggering logic in edit mode. ![Triggering_Logic](/assets/triggering-logic.png) 8. In the TL editor, on the right side of `Criteria`, click `Set`. 9. In the Criteria Editor dialog, click on `Add Condition`. 10. In the `Search Question`, find the question you created in step #2 above. :::note If your Baseline Survey is not published, you will not see the questions here. ::: 11. For the operator, choose `==`. 12. For the right operand, enter the desired code. ![Setting_Criteria_for_Baseline_Survey](/assets/setting-criteria-for-baseline-survey.png) 13. Press `Save` on the `Add Condition` dialog. You should see the criteria on the triggering logic like `Q22701_1 == 321`. 14. Press `Save` on the triggering logic. ![Triggering_Logic_Editor](/assets/triggering-logic-editor.png) 15. `Save` and `Publish` Survey A. ### 3. Enroll Participants and Monitor for the Desired Behaviour After making the above changes, when the participant joins, they will be asked to enter the code provided by the researcher. When the participant enters the code, the triggering logic will be enabled for them. The triggering logic will be disabled if the participant has not entered any code, or has entered a different code. :::info Instead of a Number question, you may choose a Single Answer question as well. This reduces the chance of participants entering an incorrect code. Note that this method relies on participants correctly entering the code shared with them. You can also monitor their responses to the Baseline Survey to ensure they have not made a mistake. ::: :::note Avicenna loads the entire study for all participants. If you enroll many participants and create personalized surveys or triggering logic for each of them, this will increase the size of your study and slow down the study loading time in the app. ::: ## Method Two: You Enter the Code For Each Participant The idea in this method is that instead of asking participants to enter the code, as we did in [Method One](#method-one-asking-participants-to-enter-a-code), you can enter the code yourself. This prevents potential errors from the participant and reduces their burden. ### 1. Create a Survey to Store Participant-Specific Variables 1. Create a new survey in your study. Let's call this `Survey B`. This will be used to store variables for enabling and disabling our triggering logic. 2. Remove all triggering logics for this survey, so participants will not see this survey. 3. Add a Number question to this survey, with the following content: `Please enter the participant's code:` 4. `Save` and `Publish` Survey B. ### 2. Enable Triggering Logic Only for Participants with the Desired Code This section is exactly like the second part of [Method One](#method-one-asking-participants-to-enter-a-code). The only difference is that instead of referencing the question from the Baseline Survey, you will reference the question from Survey B. ### 3. Enroll Participant, Enter Their Code, and Reload Their App 5. Enroll the participant in your study. At this stage, because there is no code for him/her yet, the triggering logic will be disabled. 6. Navigate to the `Activity Sessions` page and press the `Submit New Session` button. ![Submit_New_Session_Location](/assets/submit-new-session-location.png) 7. In the `Submit New Session` dialog, select `Survey B` and the participant you want the triggering logic to be enabled for. ![Activity_Session_Setting_For_One_Triggering_Logic](/assets/activity-session-setting-for-one-triggering-logic.png) 8. Press `Next`. 9. On the next page, enter the code for the participant. ![Completed_Researcher_Responded_Survey](/assets/completed-researcher-responded-survey.png) 10. Press `Submit`. 11. Now that you have entered the code for this participant, you should reload his/her phone to get the latest changes. To do so, go to the `Participation` page. 12. Find the participant. 13. From the tree dot menu next to the participant row, press `Reload Devices`. At this point, the intended triggering logic should be enabled for the specified participant and it should be disabled for all other participants. :::note You can define a [Notification Template](../../reference/study-setup-and-deployment/notifications.md#notification-templates) for `Participant Joined` events. This way, you will be informed when a participant joins the study and you can enter the code for them immediately. ::: --- sidebar_position: 5 --- # A Richer VAS Question: How to Use Images as Labels Visual analogue scales (VAS) are measurement instruments represented as sliders designed to facilitate assessing characteristics or attributes that cannot be measured directly. They are primarily used to describe the intensity, severity, or frequency of the symptoms experienced by research participants. VAS has been used in clinical research, especially those of the psychology field, for some time now. Due to its many advantages, it has successfully replaced Likert-type scales in most research projects requiring a psychometric response scale due to its many benefits. The benefits of this non-ordinal measurement instrument have been the subject of many research projects. In [a study published in 2017](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5288410/), one advantage of VAS has been explained as it being less biased than categorical scales. Moreover, respondents experiencing symptoms belonging to two categories would feel more comfortable dealing with this type of scale. VAS questions could also improve a research project's compliance rate. They have been adapted into various cultures and languages since they require very little translation for both researchers and participants, especially with the help of images. In addition, participants working with this measurement instrument need no previous training or instruction, and they can offer their responses quickly. Among many other question types, Avicenna's research tool allows the use of [VAS questions](../../reference/surveys/questions.md#visual-analog-scale-vas). Researchers can take advantage of the user-friendly survey to adjust their VAS questions towards achieving their desired outcome. With Avicenna, you can set the scale's limitation to whatever number you need, change the labels that determine respondents' selected value, and choose either a horizontal or a vertical layout for the scale. Imagine you want to add a pain scale to your survey to monitor participants' pain levels daily. Using images as labels in VAS questions can further increase the appeal and inclusiveness of your study, and Avicenna always strives to offer the best research tool features. To create a comprehensive pain scale in Avicenna, we are using six images representing the increasing level of discomfort. Here's how to modify your VAS question for that: **1-Open the Activity** In the _Researcher Dashboard_, choose your study and click on _Activities_ from the left-side panel. Here you can [create a new survey](../../getting-started/your-first-survey) or [edit](edit-surveys-during-the-study.md) an existing one. In this example, we are editing "Survey 2". ![](/assets/01-10-21--1-.png) **2-Add a VAS Question** Once you are in the _Content_ tab of the _Survey Editor_ page, click on _New Items_ from the right-side panel and choose _VAS Question_ from the list. ![](/assets/01-10-21--2-.png) You can also click on _Add a New Question_ and choose _VAS_ from the displayed menu. ![](/assets/01-10-21--3-.png) **3-Type Your Question** Now it's time to add the body of your VAS question. In this example, we are typing in the following question: "On average, how much pain did you feel today?" ![](/assets/01-10-21--4-.jpg) **4-Modify the VAS Question** To further modify the features of your VAS question, click on _Properties_ from the right-side panel. In the displayed menu, change the _Maximum_ value number to 36 to cover the range of six images. By turning on the _Show the Selection Value_ toggle, participants can submit more accurate responses. You can read more about that [here](../../reference/surveys/questions.md#visual-analog-scale-vas). Adjust the rest of the question properties as you see fit. | | | :-------------------------------: | | ![](/assets/01-10-21--5-shad.jpg) | **5-Add Image Labels** To add images to your VAS question, you need to turn the _Show Selection Label_ toggle on from the _Properties_ menu. Choose the _Label Type_ as _Image_. Click on _Select Image_ and choose a file to upload. Next, you need to set the _Lower Bound_ as 0 for this first image label. Since we have six images to use as labels in this example, we need to add new labels and set their lower bounds accordingly. Click on _Add a New Label_ and set the _Lower Bound_ as 7. The upper bound will automatically change based on your settings. ![](/assets/01-10-21--6-shad.jpg) After adding the rest of the labels, they should have the lower bounds of 13, 19, 25, and 31. Participants will ultimately be displayed a survey that looks like the following, based on their responses. ![](/assets/01-10-21--7-shad.jpg) Due to its unique design, research participants of any and all academic, social, or geographical backgrounds can answer VAS questions with minimal difficulty. Avicenna is an adaptive survey tool that offers adjustable VAS question formats. By following the instructions given above, you can customize the app's behaviour to serve your study's various needs. --- sidebar_position: 6 --- # Edit Surveys During the Study Sometimes, you might need to make a few changes to your already set-up surveys. Imagine your survey configurations are done, participants are recruited, and study is in progress, and you realize that you've made a mistake in one of your surveys that needs to be corrected. Fortunately, the Avicenna survey tool provides an easy solution for such situations. Avicenna is a very flexible tool that supports changes in the study protocols and allows for minor corrections if needed. As part of this, it allows you to make changes to surveys that are already sent to your participants. Participants who have already completed the surveys will not receive the new version, but those in the middle of their participation or who join after the modifications are able to view the new changes. Suppose that you are conducting an experience sampling research study with our survey tool, but you find a typo in one of the questionnaires after you have deployed it. Here is how you can fix it: **1. Modify the Survey** Go to your dashboard. Open the _Activities_ section from the left-side menu and choose the survey. Click _Edit_ and make the necessary changes by editing your selected survey. At this step, you can apply any changes in your surveys and customize it exactly the way you want. For more information on how to personalize surveys, see [here](personalized-surveys-in-avicenna). **2. Publish the Modified Survey** When you're satisfied with the changes you've made, click _Preview & Publish_ from the top menu. Select _Publish_ and your modified survey is good to go. ![](/assets/edit-survey-after-deployment-1-1-shad.jpg) ![](/assets/edit-survey-after-deployment-2-1-shad.jpg) **3. Reload the Study Configuration** To let your participants have access to this new version of the survey, you need to reload the study on their phone. Simply click on the _Participation_ section from the left-side menu and select all participants from the list. A new menu will appear on top of the list. Click on _Reload Device_, and your job is done. Our tool will take care of the rest. ![](/assets/edit-survey-after-deployment-3-shad.jpg) After initiating the reloading process from your researcher dashboard, Avicenna sends a notification to the participants' app which reloads the configuration from the server to their phones. On Android devices, the process happens automatically but on an iOS device, users need to open the Avicenna app either manually or by tapping on the received notification. **Alternative Solution** In cases when you are in contact with your participants, it is possible to ask them to reload the study's information manually. To do this, when you are done with your modifications (see step 1 and 2), get in touch with your participants to ask them to this manually. All they need to do is to open the app, tap on the _Settings_ icon located on the top-right corner of the app's home page, go to the _My Studies_ menu, and press _Reload Study from Server_. All configurations will be reloaded immediately and they will see the new changes in your surveys. **Additional Tips** Avicenna is a reliable research tool that accurately follows the protocol of the study exactly the way researchers configure it. However, to ensure the settings of studies are set properly, it allows researchers to put their studies through a trial run with test participants before the actual deployment. We recommend you take advantage of this feature as much as you can. After all, the trial version of Avicenna is absolutely free of charge and you can test the tool with your friends and colleagues for as long as you want. Please note that you should be careful with changing [_Time TLs_](../../reference/activities/triggering-logics#time-tl)_._ Frequent modification of _Time TLs_ while the study is in progress, might end up interrupting the study's timelines and confusing participants. --- sidebar_position: 7 --- # How to Create a One Time Optional Survey With a flexible research tool like Avicenna, you have many ways of prompting surveys to participants. By employing [User Triggering Logics](../../reference/activities/triggering-logics.md#user-tl) and setting the right [criteria](../../reference/activities/criteria.md), you can create a survey that is always accessible to participants for answering and disappears once it's completed. We pride ourselves on the reliability of our survey tool for a wide range of research studies with different requirements. Assume you're using Avicenna as a [survey tool](../../reference/surveys/) to conduct a questionnaire for an experience sampling research study. You'd like to prompt participants to take part in the survey, and keep it available for them to answer questions until the survey is completed. Here's how you would go about it: **1. Create a Survey** Go to the Research Dashboard page. Open your study and click on _Activities_. You will see a list of activities to choose from. Select _Survey_. Next, type a name and an optional description for your survey and click on the _Add_ button. This will direct you to the activity editor page. You can learn more about creating and editing surveys [here](../../reference/surveys/). To continue with our example, first, you will need to add some questions and modify their settings while in the _Content_ section. Complete your questionnaire however you see fit. Be sure to turn the _Mandatory_ toggle on for each question because the answers will be needed for the User TL. ![](/assets/create-a-survey-1.png) **2. Set a User Triggering Logic** Now it's time to start scheduling how to prompt users to take the survey. For our questionnaire to be accessible to participants until it is answered, we need to add a User TL and adjust it for this purpose. Click on _Triggering Logics_ from the top menu. This will open a window to modify the settings of different triggering logics. You can read more about TLs in general on the [Triggering Logics](../../reference/activities/triggering-logics.md) page. For our purpose, we need to have a User TL. You can either add one from the bottom menu by clicking on its icon, or edit the default User TL already provided. ![](/assets/create-user-trigerring-logic.png) **3. Set the Criteria** Since you want the survey to be prompted until it is filled out, you need to set particular criteria. The criteria would basically command the application to keep the TL enabled as long as the last question in the survey is not answered, and disable it when it is answered. In our example, all of the question types of the survey are set as [_Single Answer_](../../reference/surveys/questions#single-answer), with the _Mandatory_ toggle turned on. In this example, my survey ID is 12061 and its last question ID is 6, which has 3 options. I type the following syntax in the _Criteria_ section: This means if Q12061_6 doesn't have either 1, 2, or 3 as an answer, it's not completed, and so the User TL should be enabled. You can learn more about criteria syntax [here](../../reference/activities/criteria.md). ![](/assets/set-criteria-for-trigerring-logic.jpg) **Already created a survey?** No worries. Our flexible research tool lets you modify surveys after being saved. All you need to do is select the _Activities_ section from the left-side menu of your Researcher Dashboard to access your surveys. Click on the survey that you want to modify, and a menu will pop up on the right side of your screen. Choose _Edit_, and follow the instructions from step 2. You can read more about how to edit your surveys while your study is in progress [here](edit-surveys-during-the-study.md). ![](/assets/modify-a-survey-1.jpg) --- sidebar_position: 8 --- # How to Set Reminders Based on Participants Preferences The low compliance rate of a research work is one of the main reasons why a study fails. [A 2019 study](https://journals.sagepub.com/doi/full/10.1177/1470785319880704) on how to maximize participation in online surveys found that one of the first steps towards recruiting the appropriate participants is finding people who are interested in the researched topic, are interested in voicing their opinion, and are willing to put time and effort into taking part in a study. On the other hand, researchers can increase their chances of receiving responses by designing a clear survey and sending an attractive invitation for it. Preserving the connection between researchers and respondents is another important factor that contributes to increasing the compliance rate. Sending reminders to participants during their time on the study will induce a sense of obligation that can help your research. The number of these reminders can be decided by your participants. By considering your respondents' preferences, this obligation will be combined with a sense of respect and trust---the more personalized the experience, the greater the chance of participation. Avicenna provides various features to further personalize its users' experience with the research tool. The application's flexible study protocols allow researchers to employ the specified [notifications](../../reference/study-setup-and-deployment/notifications.md) based on participants' needs. These notifications remind participants of their registered study's activities that they need to take part in. Avicenna allows for further communication between researchers and participants by featuring single and multiple reminders for each activity. For example, researchers can give participants the freedom of choosing how many notifications they would prefer to receive every day. Imagine you are conducting a study to find out participants' daily carbohydrate consumption. As they need to log in the amount of food they eat every day in a survey, you want to send SMS notifications to participants as a reminder. If you want participants to have a say in the number of notifications they receive, you need to create two surveys and customize them accordingly. Here is how to go about it: **1-Create a Baseline Survey** To get started with the example, you can create a [baseline survey](how-to-create-a-baseline-survey-in-avicenna.md) and ask participants about their preferred number of daily survey notifications. To do that, you need to go to the _Researcher Dashboard_, open _Activities_ from the left-side panel, create a _Survey_, and name it "Baseline Survey". Once you're directed to the _Survey Editor_ page, you can add the following [_Single Answer_ question](../../reference/surveys/questions.md#single-answer) to the survey: "How many times a day would you like to receive survey notifications?" Next, add three options as "1", "2", and "3". ![](/assets/14-06-2021--1-shad.jpg) Remember the question ID, the answer IDs, and the survey ID for later. Assuming you are already familiar with the basics of survey customization, we now move on to creating the next survey. For more information on how to customize a survey, check [here](personalized-surveys-in-avicenna.md). **2-Create the Experience Sampling Survey** Following our example, we now need a survey that asks participants about their daily carb intake. To create this survey, you need to open _Activities_ from the left-side panel, create a _Survey_, and name it "Carb Intake". In the _Content_ section, add questions about common food which are high in carbohydrates. You can add a [_Number_ question](../../reference/surveys/questions.md#number) like the following: "How many loaves of bread did you have yesterday?" ![](/assets/14-06-2021--2-shad.jpg) **3-Add Notifications** Since you've asked participants to choose between one, two, or three daily notifications in the Baseline Survey (see **step 1**), you now need to add three notifications to your "Carb Intake" survey. You can schedule these notifications to happen in two-hour intervals. On the _Survey Editor_ page, click on _Notifications_ in the top panel. Select _Add a notification_ and set it to _Send the notification after 0 hours_. Next, you need to choose the type of your notification. Check _SMS_ and type in the message you want participants to receive in the text box as follows: "Don't Forget to Log In Your Carb Intake Information Today!" ![](/assets/14-06-2021--3-shad.jpg) Next, add two more notifications with the same modifications and set them to _Send the notification after 2 hours_, and _4 hours_. ![](/assets/14-06-2021--4-.jpg) Remember these notification IDs for the next step. **5-Add Triggering Logics** Now it's time to specify how and when the survey should be prompted to participants and put those notifications to use. In this example, we want each [Triggering Logic](../../reference/activities/triggering-logics.md) (TL) to prompt the survey based on participants' answers to the Baseline Survey question (See **step 1**). And according to the three answers provided, we need three TLs. Let's begin with the first one. While on the _Survey Editor page_, click on _Triggering Logics_ from the top panel. Next, add a _Time TL_ from the bottom of your screen and start modifying it in the dialog box that opens. Since you want the Time TL to prompt the "Carb Intake" survey every day, you should check the _Repeatedly trigger the activity_ button, and modify it to _Repeat Daily every 1 day_. Next, you should set [criteria](../../reference/activities/criteria.md) for the Time TL. Criteria in Avicenna allow researchers to define customized behaviours for different parts of the study. In our example, you want the first triggering logic to prompt the survey to the participant and send only one notification throughout the day. This TL only triggers the "Carb Intake" survey if the answer to question ID: 1 from the Baseline Survey (ID: 12872), is the answer ID: 1. For that, you need to type this syntax in the _Criteria_ section of the Time TL: Now that a participant is choosing to receive one notification per day, check the box next to _Use only a subset of notifications_, and delete the two extra notification IDs. Here, you can keep the one that notifies participants immediately (N ID: 0). ![](/assets/14-06-2021--5-shad.jpg) Accordingly, the second Time TLshould be added and have the following syntax in the _Criteria_ section. It should also be set to repeat daily. As the syntax shows, the second Time TL is concerned with participants who want to be notified about the survey twice a day. That means you should use only two of your defined notifications. Here, you can use the two notifications that alert participants immediately and two hours after the survey is prompted (N ID: 0, N ID: 1). ![](/assets/14-06-2021--6-shad.jpg) And for the third Time TL, all you need to do is use the following criteria syntax and modify the Time TL to repeat daily, as explained. The box next to _Use only a subset of notifications_ should remain unchecked. As mentioned earlier, sending reminders to participants is one of the most influential factors contributing to a remote study's success rate. By adding a baseline survey to your study and using the Notification and Triggering Logics features provided by Avicenna research tool, you can increase the chances of getting responses from participants. --- sidebar_position: 10 --- # Personalized Surveys in Avicenna Conducting a personalized survey means your study participants would enjoy a more unique experience. In addition, it would create a greater connection between researchers and respondents, which is especially invaluable when online surveys are involved. Survey customization of various kinds can also act as a strategy to encourage participants to continue with a research study. Using this method, each participant can receive different surveys or receive his or her survey at a different time, or his or her survey can have different questions, depending on the responses they provide throughout their participation. To use this option in your study, you just have to divide your study subjects into multiple groups, where each group consists of one or more participants. Then you define the criteria to determine which group each participant belongs to and then enable or disable certain options depending on the participant's group. Let's see how this can be done in a sample study. Let's assume I want to collect data on the impact of alcoholic beverage consumption on sleep quality. I'm planning to enroll 50 participants, and collect 2 weeks of experience sampling data from them. As part of the experience sampling, I want to ask them a short survey soon after they wake up in the morning. In the rest of this post, I will walk you through how this can be done in Avicenna. ## Creating a New Study I start by creating a new study in Avicenna called "Drinking and Sleep". I enter the name of the study, consent materials I want to be presented to the participants, and the name of the institution which conducts this study: ![](/assets/drinking-and-sleep-study-description.png) Then, I specify the timeline of the study. I want to start the study from today (Mar. 6th), and finish it by the end of April. I want to enroll 50 participants, and I expect each participant to be part of the study for 15 days. **Note:** that I want to collect 14 days of experience sampling data from each subject, but I enter 15 in order to account for partial start and the end date of their participation. ![](/assets/drinking-and-sleep-study-timeline.png) I do not plan to collect any sensor data, so I skip the Data Sources section and accept all default parameters in the Configuration section. Then I click on _Create Study_ button to create my new study. When the study is created, I will be taken to the study's dashboard and can continue with creating the surveys. ## Creating Surveys For this study, I want to create two surveys. The first one, the Baseline survey, will be presented immediately after the participant joins the study. So I create a new survey, call it _Baseline Survey_, and add a Time Triggering Logic to it with the following configurations: ![](/assets/drinking-and-sleep-study-baseline-survey.png) The Time Triggering Logic dialog is longer than this and not all the content is shown here, but I've only changed the _Base Time_ to _Study Registration Time_, and have set the first trigger to be 0 days, 0 hours, and 0 minutes after the registration time. I have not made any other changes in this dialog. Now I press _Add_ to add this triggering logic to my _Baseline Survey_. Here I will also add my two questions: ![](/assets/drinking-and-sleep-study-baseline-survey-questions.png) As you can see, I have two questions: question ID 2 which asks about the gender of the participant, and question ID 3 which asks about the usual wake up time of the participant. I write down Question ID 3 as I will need this later on to create my _criteria_. Now if I go back to the dashboard, I can see my survey listed there. The ID of this survey is `5281`. I write down the survey Id as well: ![](/assets/drinking-and-sleep-study-baseline-survey-listed.png) Now I create the second survey that I plan to use for experience sampling. I want this survey to be prompted around an hour after the participant reported they wake up in the morning. So: - If they wake up before **6 am (Answer ID 1)**, prompt **at 7 am**. - If they wake up between **6 am and 7 am (Answer ID 2)**, prompt **at 8 am**. - If they wake up between **7 am and 8 am (Answer ID 3)**, prompt **at 9 am**. - If they wake up after **8 am (Answer ID 4)**, prompt **at 9 am**. I should create one triggering logic for each of the options above, and configure it such that only one of them is enabled depending on the participant's choice. Let's start with the first one. I remove the default _User Triggered_ triggering logic, and add a new _Time Triggered_ triggering logic. Then I change the following in there: - It will remain relative to the **Study Registration Date**. - First trigger between **1st day 07:00:00** and **1st day 07:00:00**. - Repeat **every 1 day**, end after **14 occurrences**. Now before finalizing this triggering logic, we need to set a _criteria_ for it such that it's only enabled if the participant has specified she wakes up before 6 am. I am not going through the details of how _criteria evaluation_ works in Avicenna. You can read about it in detail [here](../../reference/activities/criteria.md). Here we want the triggering logic to be enabled if the participant chooses Answer ID 1 (Before 6 am) for question ID 3 in survey ID 5281. So I use the following criteria for this triggering logic: ``` Q5281_3 == 1 ``` Below is how my first triggering logic looks like: ![](/assets/drinking-and-sleep-study-experience-sampling-triggering-logic-1.png) I create the remaining three triggering logics just like the first one. The only difference is the time they each trigger the survey and their criteria. I list the criteria for each of them below, and I believe you can guess why they are written this way: - For the second triggering logic: `Q5281_3 == 2` - For the third triggering logic: `Q5281_3 == 3` - For the fourth triggering logic: `Q5281_3 == 4` The following image shows my experience sampling survey after creating all four triggering logics: ![](/assets/drinking-and-sleep-study-experience-sampling-final.png) ## Results That's all I had to do to create a study with surveys and personalized prompt time. I can now start enrolling participants. For this example, I enrolled two participants, one who reported she wakes up before 6 am (Participant #24191), and another one who reported she wakes up after 9 am (Participant #24192). To check the schedule of their surveys, I go to the `Activity Sessions` page, choose both participants, select all surveys, and choose to see their survey schedules from Day 0 (the day they joined the study and their participation started) to Day 15. ## Alternatives The above study shows how to personalize the experience sampling schedule using the participants' wake up time. You can go further and add more _wake up time_ options for the participant to choose from or can define a different prompt schedule for weekdays versus weekends. Furthermore, you can use criteria similar to what I explained above to define complex skip patterns inside a given survey. So instead of, or in addition to, adjusting the survey's prompt time, the questions for each participant also can be different depending on the participant's responses to the baseline survey. Or you can use [_Placeholders_](../../reference/surveys/questions.md#placeholders) to modify the questions' content, and making the questions more personalized. Another solution is to use sensors. If we assume people often check their phone while they are awake but not while they are asleep, we can use the [_Screen Time_](../../reference/data-sources/from-smartphone/screen-state.md) data source to estimate the sleep and wake up time of each participant, and prompt the surveys shortly after they wake up. To achieve this, I should include the _Screen Time_ data source to my study, so the Avicenna app collects this data from all participants. Then I define an _Advanced_ triggering logic to process the data and decide when the survey should be prompted. This triggering logic would analyze the screen time in real-time, detect scenarios that we can mark as _wake up time_, and prompt the survey. Note that unlike other scenarios above, in this case, participants would have to be online at all times. If you are interested to know more about this solution, or if you have any other questions, feel free to ask in our forum, or email our [support team](mailto:support@avicennaresearch.com). --- sidebar_position: 11 --- # Prompt a Survey More Than Once a Day For some studies, you might want to notify the participants to take a survey, or complete a cognitive task, more than once a day. In such cases, you should use multiple Time Triggering Logics (or Time TL, for short). Fortunately, Avicenna has made it possible to add more than one Triggering Logic to your study. Now, let's walk through adding multiple Time TLs to a survey together. Say we want to prompt our survey 3 times a day, at 9 am, 2 pm , and 8 pm. Here's how to do it: ## 1. Open Your Study Click on the Avicenna logo from the left menu of your Dashboard to see your studies. Choose the one you want to modify. ## 2. Open the Activities Section You can see the _Activities_ below your study's information box. Click on that to go to the _Activities_ section. Alternatively, you can click on the _Activities_ from the left-side menu. ## 3. Edit The Survey You can see the list of the activities related to your study. Click on the survey that you want to modify. A menu appears on the right side of the screen. Choose the _Edit_ option. ## 4. Add a Time Triggering Logic Here you should select the Triggering Logics option from the top menu. There, you will find a list of Triggering Logics at the bottom of the page. Choose _Time_. ![](/assets/time-triggering-logic.png) ## 5. Modify the Time TL A window opens in which you can modify the characteristics of your Time TL. You can specify a _Criteria_, set a _Base time_, include a time _Period_ in which the survey should be prompted and more. To learn more about how to modify Time TLs in general, take a look at [here](../../reference/activities/triggering-logics.md#time-tl). Going along with our example, we need to set the trigger at 9 am, 2 pm and 8 pm. We'll do 9 am first. Simply let the _Period_ toggle stay off and set the time of the _First Trigger_ to 09:00:00. For your survey to be prompted at 9 am everyday, you have to check _Repeatedly trigger the activity_ from the _Repetition_ section. Now you can choose to repeat the activity daily, weekly, monthly or yearly. For our purpose, choose Daily and every 1 day, then click _Save_. This means that your participants will receive a notification to take the particular survey at 9 am every day. ![](/assets/capture-shad.jpg) ## 6. Repeat! To prompt the participants to take the survey more than once each day, you would have to add as many Time TLs as you need. So now that we need the survey to also be prompted at 2 pm and 8 pm each day, we can add two more Time TLs (see Step 4). For the first one, we will set the time of _First Trigger_ to 14:00:00 and modify the rest of the settings as explained before. Likewise, the second extra Time TL should be added and modified, except that it will be set to 20:00:00. Now your participants will be reminded at 9 am, 2 pm and 8 pm everyday to take the survey. --- sidebar_position: 12 --- # How to Create a Baseline Survey in Avicenna Executing a long-term study that keeps participants engaged requires thoughtful planning. This involves providing incentives, having clear onboarding processes, and offering flexible adherence routines to participants. Using baseline surveys can be the first step in achieving these. Baseline surveys are powerful instruments for collecting essential information from participants at the beginning of the study. This information allows personalizing your studies for each participant, and in turn, increases participant adherence and retention. In Avicenna, you can easily create a baseline survey for your study to be presented immediately after the participant enrolls. In this How-To, we want to set up an experience sampling study, where people between the ages of 18 to 55 receive a certain set of surveys, while those 55+ get a different set of surveys. To do this, you need to create a baseline survey that asks participants about their age. Then program your study to present different flow based on the participant's age. To do so: 1. **_Create a Baseline Survey_** Navigate to the Researcher Dashboard and select `Activities`. Click on `Create New Activity` and create a [Survey](../../getting-started/your-first-survey.md). Let's name it Baseline Survey. After entering a name and description, Avicenna will navigate you to the Activity Editor page. ![Create a baseline survey](/assets/how-to-create-baseline-survey-new-survey.png) In the Content section, you can add your questions. For this example, type in the question: "How old are you?". Add these two answers: "18 - 55" (ID 1), and "56 - 90" (ID 2). ![A sample question for the baseline Survey](/assets/how-to-create-baseline-survey-sample-question.png) Navigate to Properties from the right-side panel and enable the Mandatory option. This setting ensures participants must answer this question before progressing with the rest of the survey. 2. **_Add a Triggering Logic_** In the Activity Editor, click on Triggering Logics from the top panel. Remove the default User Triggering Logic (TL). Then add a Time TL from the bottom menu. ![Adding Time Triggering Logic to Baseline Survey](/assets/how-to-create-baseline-survey-add-time-triggering-logic.png) Then to only prompt the survey once, after the participant's registration, set the Time TL's setting according to the picture below: ![Time Triggering Logic in more detail](/assets/how-to-create-baseline-survey-add-time-triggering-logic-in-detail.png) :::note Make sure you set the Base Time to Study Registration Time. This way, the participant will receive the survey immediately after the registration. ::: 3. **_Save and Publish Your Changes_** To save the modifications you've made to the survey, click on the `Save` button in the top right corner. To publish the survey, click on the Preview & Publish page, and in the Publish tab, click on `Publish`. 4. **_Insert the Experience Sampling Surveys_** Now, we need to create two surveys; One for those between 18 to 55 and another for those older than 56. At this level, we are hoping that you are comfortable with creating a survey. If not, make sure you check [this article](../../getting-started/your-first-survey.md). After creating the first survey, navigate to the Triggering Logic section, and input `Q19449_1 == 1` in the Criteria section. This means that the first survey will be available for participants who answered 1 (age 18 to 55) in the Baseline Survey. ![First Survey for Experience Sampling](/assets/how-to-create-baseline-survey-experience-sampling-survey-1.png) Repeat the same process for the second survey, but input `Q19449_1 == 2` in the Criteria section. ![Second Survey for Experience Sampling](/assets/how-to-create-baseline-survey-experience-sampling-survey-2.png) :::info You can also use your baseline survey to ask about participants' preferences, such as when to receive a notification from the app. You can learn more about that [here](../../reference/study-setup-and-deployment/notifications.md). ::: In summary, baseline surveys serve as an essential tool for customizing your long-term studies to each participant's specific conditions or preferences. In this example, you learnt how to create an age-specific experience sampling study. So go ahead, and try out the baseline surveys in your research. If you have any questions, feel free to reach out to us via support@avicennaresearch.com or via our [forum](https://forum.avicennaresearch.com). # Add an "Other" Option to Single Answer or Multiple Answer Questions When creating a survey with `Single Answer` or `Multiple Answer` questions, it might be important to allow the participants the flexibility to enter their own answer if it's not provided as an option. To achieve this, you can include an `Other` option in the answer choices and add a follow-up `Text` question where the participants can type in their answers. In the steps below we use a `Single Answer` question but the same flow can be applied to `Multiple Answer` questions. 1. Add the `Single Answer` question along with the available answer options. For example, let's say the question should ask for the participant's favorite color: Red, Green, and Blue. 2. Add the `Other` as an option at the end of the list of answer options. 3. Add a `Text` question right after the `Single Answer` question. 4. Set a `Criteria` for the `Text` question based on the `Other` answer option from the `Single Answer` question. In our example, as you can see, the `Criteria` should be set to `Q1 == 4`. This configuration ensures that if a participant selects `Other`, they will be prompted with a `Text` question where they can enter their answer. ![Criteria for the Text question](/assets/criteria-based-on-other-answer-option-of-single-answer-questions.png) 5. (Optional) You might want to change the `Type` of the `Text Question` to `Single Line`, since colors are either one word or a phrase. 6. Save and publish the survey. ![Overview of the survey](/assets/other-answer-option-for-single-answer-questions.png) # Customize Survey Notifications Based on Participants' Preferences One of the most challenging parts of conducting an experience sampling research study is finding willing participants to enroll in the research project. However, keeping these participants interested for the duration of the research is perhaps an even harder task, which is directly related to the compliance rate of the research. This is especially a bigger problem with long-term or longitudinal studies. There are many ways to customize your experience sampling research to increase the compliance rate. One of them is setting an alert or notification system that reminds participants to put in their diary in whatever research tool you’re using. Avicenna is constantly trying to develop innovative ways to facilitate survey personalization for both researchers and participants. As one of the useful features of our survey tool, studies can be customized to prompt various activities to participants via notifications. Avicenna offers three options for that: In-App, SMS, and Email notifications. This poses a chance to take advantage of the very flexible study protocols that Avicenna provides. In some cases, researchers like to give their participants the freedom to choose a preferred method. That is because it can allow for a larger group of people to take part in the study, no matter their accessibility status: e.g. an elderly person, not comfortable with checking their email daily, can benefit from an SMS notification; participants whose phones limit app notifications will get notified via email; people who don’t like notification clusters can opt for only in-app notifications; etc. In order to find out your participants’ preferences about how to receive notifications, it is possible to ask them a question at the beginning of the study. You can do this in a baseline survey. Assume you are about to conduct an experience sampling study, which requires participants to log in their emotional state at the end of the day, every day, in a survey. You want to notify the participants to complete this survey based on their preferred method. Here is how to do it: ## 1. Create a Baseline Survey It is easy to create a baseline survey with our research tool. Your participants’ answers to the baseline survey’s questions could help adapt the survey tool’s behavior regarding your study, as well as positively influence your research study’s compliance rate. To create a baseline survey, go to Researcher Dashboard and choose Activities from the left side menu. Next, click on New Activity and [add a Survey](../../reference/activities/README.md#accessing-activities), then name it “Baseline Survey”. Afterward, you will be directed to the Survey Editor page, where you can modify your baseline survey. In the Content section, you can add as many questions as you like. In our example, you would want to add a Single Answer Question by clicking on Add a New Question and type in the question as: “How would you like to be notified about new activities?”. Next, add the three answers that participants can choose from. ![Baseline Survey - First Question](/assets/customize-survey-notifications-based-on-participants-preferences-baseline-survey-first-question.png) Add another question asking participants about what time they usually sleep at night and provide the answers to choose from as follows: ![Baseline Survey - All Questions](/assets/customize-survey-notifications-based-on-participants-preferences-baseline-survey-all-questions.png) Remember the question IDs and answer IDs for later use. ## 2. Add a Triggering Logic Now you need to add a [Triggering Logic](../../reference/activities/triggering-logics.md) (TL for short) to your survey from the top menu. Add a User TL from the bottom menu, or edit the existing default User TL provided by the app, and modify it to look like this: ![Triggering Logics](/assets/11-06-2021--2-.jpg) ## 3. Save Your Modifications You can click on Save from the top menu of the Survey Editor page to edit and publish the survey later. Or publish your survey then and there by clicking on Preview & Publish. ![Save Survey](/assets/11-06-2021--3-.png) ## 4. Create Your Survey Now it’s time to create a survey that you can use for experience sampling. Following our example, we need a survey that asks participants about their everyday emotional state. Create a survey via the Activities menu, and name it “Daily Mood”. Next, in the Content section of the Survey Editor page, add a VAS Question and type in the following: ``` On a scale of 1 to 100, how happy do you feel today? ``` ![Daily Mood Survey](/assets/11-06-2021--4-.jpg) ## 5. Add Triggering Logics Next, you need to add Time Triggering Logic to the survey, so that it is prompted to the participants at the end of the day, one hour before bedtime. Since you provided three options for bedtime in the baseline survey, you need to add three Time TLs. Choose Triggering Logic from the top menu, delete the default User TL, and add a Time TL from the bottom menu. Set the Base Time to Study Registration Date, and First Trigger to happen After 0 days at 18:00:00. Also, select the Repeatedly trigger the activity option and set it to Repeat Daily every 1 day. Scheduling the survey to be prompted specifically to participants who said they sleep between 7 and 9 pm requires modifying [criteria](../../reference/activities/criteria.md) for the TL. Criteria in Avicenna allows researchers to define a customized behavior for different sections of their studies with a simple programming language. You can learn more about that [here](../../reference/activities/criteria.md#syntax). In this example, the first Time TL’s criteria syntax would be: ``` Q12061_2 == 1 ``` This means that if the answer to question ID 2 (“When do you usually sleep at night?”) from survey ID 12061 (“Baseline Survey”) is answer ID 1 (“Between 7 and 9 pm), the “Daily Mood” survey should be prompted at 6 pm. ![Time Triggering Logics](/assets/11-06-2021--5-.jpg) Add two more Time TLs and configure them the same way to be prompted an hour before the participants’ chosen bedtime. The criteria syntax for each of them would only change based on the answer ID: ``` Q12061_2 == 2 ``` and ``` Q12061_2 == 3 ``` ## 6. Add Notifications Now it’s time to add a notification so that the participants receive an alert when the survey is prompted. Go to Notifications from the top menu, and click on Add a Notification. In the dialog box that opens, you can see that Avicenna provides three types of notifications. First, choose In-App. You need to add two more notifications to allow for SMS and Email notifications as well. Choosing In-App and Email means that you need to add a Title/Subject and Description/Body to your notification, and selecting SMS requires you to type in a message in the Text box. These are the messages your participants will receive. For the In-App notification, type in the following message in the text box: ![In-App Notification](/assets/11-06-2021--6-.png) ## 7. Set the Criteria For these notifications to be enabled based on each participant’s individual preference, you need to add criteria to them. In our example, you let the participants choose how to receive notifications by answering a question in the baseline survey: “How would you like to be notified about new activities?”. This question had the ID of 1 and was part of a survey with the ID of 12061. Participants could choose between “In-App Notification” (Answer ID: 1), “SMS Notification” (Answer ID: 2), and “Email Notification” (Answer ID: 3). Go to your defined In-App Notification. Based on these specifications, you need to type the following syntax in the Criteria section: ``` Q12061_1 == 1 ``` This means that the In-App Notification will only be enabled for participants who choose answer 1, “In-App Notification”. Likewise, the Criteria for the SMS Notification would look like this: ``` Q12061_1 == 2 ``` And for the Email Notification: ``` Q12061_1 == 3 ``` ![SMS Notification](/assets/1-06-2021--7-.jpg) # Schedule Sessions with Customized Timing for Each Participant Avicenna's [triggering logics](../../reference/activities/triggering-logics.md) already cover most use cases, but surely there will be cases where you want to prompt surveys on certain schedules, and none of our triggering logics fit. For full flexibility, we offer the following: - [Release an activity](../../reference/activities/activity-sessions.md#releasing-an-activity) to instantly deliver it to participants (for example, when immediate action is required). - Schedule individual sessions [through the calendar interface](../../reference/activities/activity-sessions.md#using-the-calendar). - [Upload a CSV file](../../reference/activities/activity-sessions.md#using-a-csv-file) containing the list of sessions, to create multiple sessions at once. In this article, we'll focus on the third approach. ## The Situation The participant pool includes those scheduled for a surgery. Each participant's surgery date will be different. You want to prompt them with a survey on a daily basis at 9 o'clock for 10 days following their surgery. ## What to Do? 1. **Create your daily survey**. Do not add any triggering logic to it, and delete the existing default triggering logics. [Save and publish](../../reference/surveys/README.md#publish-surveys) the survey. Ignore the warnings. ![Activity editor with no triggering logic](/assets/activity-editor-with-no-triggering-logic.png) 2. **[Create a baseline survey](how-to-create-a-baseline-survey-in-avicenna.md)** so you can get the surgery date of each participant. The survey should have one [calendar question](../../reference/surveys/questions.md#calendar) with its `Selector` set as `Date`. You can add more questions if you want of course. ![Baseline survey with the surgery date question](/assets/baseline-survey-with-surgery-date-question.png) 3. **[Create and link a notification template](../../reference/study-setup-and-deployment/notifications.md#notification-templates)** **to the baseline survey** to get notified whenever a participant submits the baseline survey. This is essential if you don't want to schedule sessions late. ![Activity editor with a "Session Completed" notification template linked](/assets/activity-editor-session-completed-notification-template-linked.png) 4. **To generate CSV files for upload**, you can use tools like R, Python, Excel, or Google Sheets. We go with Google Sheets here. Open your spreadsheet. Create two sheets. Let's name the first one `CSV` and the second one `Parameters`. ![CSV and Parameters sheets](/assets/parameterized-google-spreadsheet-for-sessions-csv.png) 5. **Define three parameters in the second sheet**: `Participant ID`, `Survey ID`, and `Surgery Date`. You can set some values for them. ![Parameters sheet](/assets/parameterized-google-spreadsheet-for-sessions-csv-parameters.png) 6. **Go to the first sheet and define three columns**: `user_id`, `activity_id`, and `scheduled_time`. The sheet should have 10 rows (+1 header row). Use the Google Sheets formula and parameters to populate the first sheet: - For cells under the first column, use `= Parameters!$B$1`. - For cells under the second column, use `= Parameters!$B$2`. - Since the scheduled times in the CSV you're going to upload should be in milliseconds since the Unix epoch, for cells under the third column, use this formula: ``` = (DATE(YEAR(Parameters!$B$3), MONTH(Parameters!$B$3), DAY(Parameters!$B$3) + (ROW() - 1)) + TIME(9, 0, 0) - DATE(1970, 1, 1)) * 86400000 ``` ![CSV sheet](/assets/parameterized-google-spreadsheet-for-sessions-csv-populated.png) 7. **Download the first sheet as a CSV**. ![Downloading the CSV sheet](/assets/parameterized-google-spreadsheet-for-sessions-csv-download.png) 8. **[Upload the CSV into Avicenna](../../reference/activities/activity-sessions#creating-a-session).** ![Uploading the CSV](/assets/parameterized-google-spreadsheet-for-sessions-csv-upload.png) 9. **To see the generated sessions more easily**, you can switch to the `Year` view mode. ![Activity Sessions in "Year" view with the generated sessions](/assets/activity-sessions-year-view-with-sessions.png) ## Pro Tips This article hasn't considered the participant's timezone or the daylight saving time for the sake of simplicity; the date/time values will be in UTC when uploaded and after the upload, you might notice a shift in the time (and probably date). You can define the participant's timezone or the date range for daylight saving time as new parameters and adjust the formula for the `scheduled_time` column accordingly. That being said, we're going to improve how we handle the date/time values in the future. --- title: Analysis sidebar_position: 3 --- # Data Analysis How-To Articles This section contains How-To articles related to accessing data, exporting them, and analyzing it: - [Making Sense of Your Surveys Exported Data](making-sense-of-your-surveys-exported-data.md) # Making Sense of Your Surveys Exported Data Conducting a research study using web-based technologies offers many advantages, from better accessibility for participants to various data collection methods for researchers. A study on [the implementation of clinical research trials using web-based and mobile devices](https://doi.org/10.1186/s12874-017-0324-6) presents doable solutions for executing meticulous patient privacy measures as well. Scientists can also benefit from having access to comprehensible, categorized data that is reportable at any time during the study. This can be used as a reliable backup strategy as well. In addition, professional online research tools allow you to continuously monitor the data collection process and consequently speed up the analysis procedure. With Avicenna, researchers have the option to view or export and analyze data: a) Data analysis in quantitative as well as qualitative research studies can be facilitated with the help of specific software such as [_Kibana_](../../reference/analysis/kibana-basics/). b) Apart from access to Kibana, it is also possible to view your collected data directly from your Researcher Dashboard's [Activity Sessions](../../reference/activities/activity-sessions.md), [_Audit Trail_](../../reference/study-setup-and-deployment/audit-trail.md), or _Survey Responses._ c) Avicenna allows for data export in the form of CSV files and more. You can conveniently import such files into your preferred data analysis tool. To export your survey data, there are three easy steps to follow: **1-Go to the Survey Response Page** Open the Researcher Dashboard and click on _Survey Responses_ from the left-side panel. Next, choose your study from the drop-down menu on top of the screen. ![](/assets/08-10-21--1---survey-responses--1.png) **2-Select Your Data** Next, choose your selected participants from the drop-down menu. You also have the option to select _All Participants_ and view their responses. You can select one survey from the drop-down menu and click on either the [_Display_](../../reference/surveys/view-responses.md) or the _Export_ button. ![](/assets/08-10-21--2---select-survey--participants-.png) You also have the option to choose multiple or _All Surveys_. However, this will deactivate the _Display_ button, and you can only export such data. By clicking on the _Export_ button, the following message will appear: ![](/assets/08-10-21--3---go-to-export-data-.png) **3-Download Exported Data** Clicking on _Export Data_ will redirect you to its page. There you can see your requested survey or surveys' data file on the displayed table. Choose _Click to download,_ and you're all set! ![](/assets/08-10-21--4---data-export-.png) **Reading Your Survey's Exported Data:** Now it's time to open and study your exported file. As an example, we have here the exported data of a survey with two questions, answered by two participants. The CSV file comes with clearly defined columns that are explained here: ![](/assets/08-10-21--5---csv-.png) **Name:** This is the participant's User ID in Avicenna. **Device ID:** This is the unique ID of the device used to respond to the survey. If a participant uses multiple devices for responding in different [sessions](../../reference/terminology.md#session), it is recorded in the exported data. **Scheduled Time:** This is the time that the survey was scheduled to be prompted and when the session for a survey is created. The recorded time depends on the triggering logics set for the survey. **Issued Time:** This is the time that the participant receives the notification for the survey. It is usually the same as the Scheduled Time but might be slightly different. **Response Time:** This is the time when the participant has provided the recorded response and concluded the session. **Duration:** This is the time it took the participant to complete the session. **Question Type:** You will see one or more of the following question types in your CSV file, alongside the corresponding question content. The responses given to each question will appear under it, in the same row as their respondent. Question types are identified with the following abbreviations: SAQ: [Single Answer](../../reference/surveys/questions.md#single-answer) MAQ: [Multiple Answer](../../reference/surveys/questions.md#multiple-answer) AUT: [Audio/Text](../../reference/surveys/questions.md#audio-text) IMG: [Image](../../reference/surveys/questions.md#image) AUD: [Audio](../../reference/surveys/questions.md#audio) VID: [Video](../../reference/surveys/questions.md#video) VAS: [Visual Analog Scale](../../reference/surveys/questions.md#visual-analog-scale-vas) MAS: [Mass](../../reference/surveys/questions.md#mass) LEN: [Length](../../reference/surveys/questions.md#length) BAR: [Barcode](../../reference/surveys/questions.md#barcode) CAL: [Calendar](../../reference/surveys/questions.md#calendar) NUM: [Number](../../reference/surveys/questions.md#number) FFT: [Text](../../reference/surveys/questions.md#text) / [Information](../../reference/surveys/questions.md#information) Whether you are monitoring your data or analyzing it, the data export feature can be beneficial for your study. Avicenna offers a user-friendly data export process that results in a detailed yet easy-to-read file(s) that can be imported into professional data analysis tools. --- sidebar_position: 1 --- # HappyB: Being, Body, and Brain According to the American Psychological Association (APA), well-being corresponds to "a state of happiness and contentment, with low levels of distress, overall good physical and mental health and outlook, or good quality of life." This definition believes that well-being does not result from the simple absence of psychological problems, but is positioned on a continuum between deficit framework (psychopathological symptoms) and well-being (positive functioning, hedonic, eudaimonic, social well-being). In the scientific literature, the biology of well-being has been studied, especially eudaimonic wellbeing, which predicts healthier lifestyle habits (more motivation to take care of oneself, less stress, and positive regulation of the neuroendocrine, cardiovascular, inflammatory, and microbiome systems). In addition, greater well-being reduces the onset of physical and mental illnesses, predicts a sustained positive response to positive experiences in the brain, and better emotional regulation. Well-being predicts all these benefits even in the presence of socio-economic and educational inequalities. According to [a UNICEF report](https://www.unicef.ch/it/media/2919/download), in Switzerland, in 2021, a third of young people between the ages of 14 and 19 had mental health problems: 45.4% had low emotional well-being, 31% had low self-esteem, 44.9% had suicidal thoughts (8.7% attempted suicide), and 37.3% had symptoms of anxiety and/or depression. It therefore seems increasingly crucial to talk about the well-being of today's young people and how new technologies can have an impact on their health. The **HappyB project** included two studies. In Study I, the aim was to investigate how smartphone and social media use are related to adolescents' well-being, over and above the illness model of well-being. In Study II, the aim was to disentangle the person-specific effects of media use on well-being daily, by collecting data with Avicenna mobile apps installed on participants' devices. In general, the project aimed to answer the following research question: How is smartphone and social media use associated over time with positively conceptualized well-being at the level of state and trait? The project was funded by the Swiss National Science Foundation and carried out in collaboration with USI Università della Svizzera Italiana, Lugano, and the Lee Kum Sheung Center for Health and Happiness, Harvard T.H. Chan School of Public Health, Boston, USA. The data were collected in Switzerland, in the Canton of Ticino. You can read more about this project, its methodology, its results, and many more details [here](https://www.laura-marciano.com/happyb). ## Study Profile **Participation duration:** 2 years (2022-2023) **Sample size:** ~1600 **Data sources:** - Surveys - Screen state - Battery status ## Research Team **Dr. Laura Marciano** Principal Investigator Harvard T.H. Chan School of Public Health, Boston, USA Institute of Public Health, USI, Lugano **Alessia Robbiani** Master Student in Clinical Psychology University of Lausanne (CH) **Susanna Morlino** Cognitive Psychologist and Communication Expert **Soumya Mohanty** Master Student in Global Health and Population Harvard T.H.Chan School of Public Health **Sundas Saboor** Ph.D. Student in Health Behavior and Health Education University of Michigan School of Public Health, USA **Adrián Medina** Developmental Scientist and Population Mental Health Specialist --- sidebar_position: 2 --- # Real-time well-being measures INTERACT is a pan-Canadian research collaboration of scientists, urban planners, public health officials, and engaged citizens uncovering how the design of our cities is shaping the health and well-being of Canadians. We track changes in urban environments and the resulting impact on people’s mobility, interactions, and well-being, including inequalities in both exposures and outcomes. To do this, we use a diverse set of tools, including the Avicenna app to capture participants’ mobility patterns, physical activity, and well-being. We use Ecological Momentary Assessment (EMA) questionnaires, an ambulatory data collection method with measures obtained in real-time, in a real-life context, and which are repeated (Shiffman, Stone, & Hufford, 2008). EMA is particularly interesting for the measurement of hedonic well-being (Liu, Xie, & Lou, 2019), given that it can capture self-reported data ‘in the moment’ via a smartphone application. EMA may reduce recall bias by asking questions about the present moment (e.g. ‘At this moment, I feel…’). The possibility for repeated assessments allows capturing potential daily variations in affective states that could be linked to environmental conditions or actual behaviors (Shiffman et al., 2008). Because EMA responses can also be tagged with GPS coordinates, it is possible to link momentary effects with environmental conditions obtained from existing GIS layers (Shiffman et al., 2008). In our study, we program surveys with questions from the Short Mood Scale (Wilhelm & Schoebi, 2007) for 7 days in a row, 3 times a day. It is comprised of 6 questions on mood (3 dimensions: valence, calmness & energetic arousal, 2 bipolar questions per dimension). We also record the location of the participant at the time of completing the survey. With this data, we observe intra-person and intra-day variations in mood and study these in relation to the types of environments in which participants are at the time of completing the survey. By enabling cities to measure and optimize the health benefits of their investments, our research aims to inspire sustainable urban development that will leave a lasting impact on population health, well-being, and equity in Canada. ## Study Profile **Participation duration:** 30 days **Sample size:** 200-600 participants per site **Data sources:** - Surveys - Location information - Motion recognition ## Research Team **Yan Kestens, Ph.D.** École de Santé Publique de l'Université de Montréal Centre de recherche du CHUM **Meghan Winters, Ph.D.** Faculty of Health Sciences Simon Fraser University **Daniel Fuller, Ph.D.** Canada Research Chair in Population Physical Activity Memorial University of Newfoundland --- sidebar_position: 3 --- # MEDIATICINO2.0 Born at the advent of the 21st century, today’s adolescents have grown up with digital media from an early age. As “digital natives” they have quickly become used to personalized and always accessible media contents, one-to-one or one-to-many communication through instant messaging, and the hands-on information and services digital devices offer. The growing diffusion of digital media such as tablets and smartphones among adolescents goes in hand with an increasing scientific interest in the benefits and risks of these devices for adolescent well-being. However, research to date on Internet and mobile media use in adolescents has two major methodological drawbacks, i.e. the predominant use of cross-sectional and self-report data, with implications on the valid, reliable, and complete assessment of digital media use and the identification of causal relationships with adolescent well-being. The longitudinal MEDIATICINO2.0 study, financed by the [Swiss National Science Foundation](http://www.snf.ch/en/Pages/default.aspx), aimed to overcome these limitations by combining objectively recorded data on smartphone use (e.g., screen state, app usage) via the Avicenna application with survey responses in a sub-sample of 100 subjects as part of a larger survey-based study with approximately 1’400 middle school students in Canton Ticino, Switzerland. As such, the study allowed to examine the causal relationship between smartphone use and adolescent well-being, and it further allows to evaluate the discrepancy between self-report and objectively recorded smartphone use. ## Study Profile **Participation duration:** 45 days in 2018 and 45 days in 2019 **Sample size:** 100 subjects **Data sources:** - Screen state - Surveys - WIFI signals in the surrounding environment - Battery status - Motion recognition and pedometer - App usage ## Research Team **Anne-Linda Camerini, Ph.D.** Faculty of Communication Sciences USI Università della Svizzera italiana (Lugano, Switzerland) **Laura Marciano, Ph.D. Candidate** Faculty of Communication Sciences USI Università della Svizzera italiana (Lugano, Switzerland) --- sidebar_position: 4 --- # Migrants and brokers The relationships between low-skilled labor migrants and local employment brokers help shape migrants' experiences and outcomes. Exactly how, though, remains poorly understood. As a result, researchers, policy-makers, and activists have yet to settle on how best to protect migrants (and brokers) from exploitative situations. For example, providing information directly to migrants and brokers may help them guard against unscrupulous practices in the migration industry -- but also potentially lead to unintended negative consequences. With our project, we aimed to understand the intended and unintended consequences of providing information to migrants and brokers in the labor recruitment context. Specifically, we asked: What is the nature of the migrant and broker relationship? What kinds of information about both this relationship and migration opportunities help migrants achieve better migration outcomes? How do brokers respond to better-informed migrants? To answer these questions, we used Avicenna Research's research platform to implement a digitally networked field experiment in a high out-migration city in Pakistan. Through Avicenna Research's participant app, we first mapped the relationships between migrants and brokers. Then, migrants participating in our study received information about brokers in their neighborhood and current employment opportunities. Brokers, in turn, received information about migrants becoming better informed. Finally, we administered short questionnaires using the Avicenna Research's participant app to measure how this information influences participants' experience with the labor recruitment process as it unfolds. ## Study Profile **Sample size:** ~500 subjects **Data sources:** - WIFI signals in the surrounding environment - The phone calls statistics - Text messages statistics - Location information - Surveys ## Research Team **Daniel Karell, Ph.D.** Assistant Professor Division of Social Science New York University Abu Dhabi **Rabia Malik, Ph.D.** Assistant Professor Mushtaq Gurmani School of Humanities and Social Sciences Lahore University of Management Sciences (LUMS) --- sidebar_position: 5 --- # Students and Adversity in a Globalized World People deal differently with challenges in their lives, depending on who they are. We propose to investigate how differences in character help to understand how students deal with adversity. Students face different types of adversity, including academic stress (e.g., the pressure to perform, negative feedback) and, in the case of international students, acculturative stress (i.e., the stress associated with staying abroad). International students are increasing in number world-wide, including in the Netherlands, but little is known about how these geographically and culturally mobile populations deal with academic and acculturative stress and adversity. We used a longitudinal, experience sampling study to investigate how character affects how international and Dutch students deal with different types of adversity. We expected that individuals’ characters are predictive of adjustment and academic success. Understanding, not only differences between groups of students but also differences between individuals’ characters and their unique ways of dealing with challenges will be instrumental to increase intervention effectiveness (e.g., introduction weeks, counselling practices, activities of student associations). ## Study Profile **Sample size:** ~250 subjects **Data sources:** - Surveys ## Research Team **Michael Bender, Ph.D.** Assistant Professor Department of Social Psychology Tilburg University, NL **Jia He, Ph.D.** Assistant Professor Department of Methodology Tilburg University, NL **Mark Brandt, Ph.D.** Associate Professor Department of Social Psychology Tilburg University, NL --- sidebar_position: 6 --- # Wellbeing of Tertiary Students University is a time of great challenge for students, offering great opportunities for learning and growth but also posing considerable challenges. A key task for Universities is to help their students succeed and achieve their potential. However, the information upon which service and policy decisions might be made is typically limited: gathered mainly at one point in time (upon enrolment), fragmented, and limited to a relatively small selection of variables. The study, then, aims to investigate the broader social, cultural, economic, and individual determinants and trajectories of health and wellbeing in students, in order to provide a detailed evidence base to inform decisions on student services and health and wellbeing policies, as well as teaching and learning experiences. The study design took full advantage of Avicenna's data collection capabilities, utilizing sensor data, baseline surveys administered upon enrolment in the Study, and very short surveys (or Ecological Momentary Assessments) delivered three times per week. By combining these data sources with anonymized administrative data from the students' University, a rich picture of the determinants and outcomes of wellbeing may be created, with the historical dimension of the data potentially allowing insight into causation. ## Study Profile **Participation duration:** 1 year **Sample size:** 180 subjects **Data sources:** - Surveys - Location information - Screen state - Proximity - Ambient temperature - Ambient light - Air pressure - Accelerometry - Pedometer ## Research Team **Andrew Page, Ph.D.** Chair of Epidemiology Translation Health Research Institute Western Sydney University **Anton du Toit** Western Sydney University --- sidebar_position: 7 --- # SMART Study ## Engage citizens to overcome the physical inactivity Physical inactivity is the fourth leading cause of death worldwide, costing approximately $67.5 billion/year to healthcare systems. To curb the physical inactivity pandemic, it is time to move beyond traditional approaches and engage citizens by re-purposing tools such as smartphones. To curb the physical inactivity pandemic, it is time to move beyond traditional approaches and Using smartphones to engage citizens to overcome the physical inactivity pandemic The primary objective of the SMART Study(www.smartstudysask.com) was to use Avicenna to prototype and validate a mobile and citizen science methodological platform for active living surveillance, knowledge translation, and policy interventions. This quasi-experimental investigation was designed to engage participants (i.e., citizen scientists) in Regina and Saskatoon, Saskatchewan, Canada, in 4 different seasons across 3 years. In Spring 2017 (1st cycle), 216 adult citizen scientists (≥18 years) were recruited in person, and online, through a combination of convenience sampling and self-selection. Citizen scientists installed the Avicenna application on their personal Android or iPhone device for 8 consecutive days to provide a complex series of objective and subjective data. They answered a succession of validated surveys that were pilot-tested to assign different smartphone triggering mechanisms (e.g. user-triggered, scheduled-triggered) to maximize compliance. The validated surveys captured physical activity (IPAQ), sedentary behavior (Adapted PACE survey), motivation (PALMS), the perception of the outdoor and indoor environment (Adapted NEWS), and eudaimonic well-being (QEWB). Ecological momentary assessments were employed on each day to capture not only physical activity but also physical and social contexts along with barriers and facilitators of physical activity, as relayed by citizen scientists using geo-coded pictures and audio files. To obtain a comprehensive objective picture of participant GPS-based location data, motion-based activity, and interaction with smartphone was also surveilled for 8 days. Initial descriptive analyses were conducted using geo-coded photographs and audio files. Pictures and audio files (i.e., [community voices](https://www.smartstudysask.com/community-voices)) showed that the barriers and facilitators of active living included intrinsic/extrinsic motivations, social contexts, and outdoor/indoor environment, with pets and favorable urban design featuring as the predominant facilitators, and work-related screen time proving to be the primary barrier. Future analyses will focus on the validation of ecological momentary assessments and smartphone objective measures to lay the foundation for simulation modeling using big data. ## Study Profile **Participation duration:** 1 week per season for 3 years **Sample size:** 320 subjects **Data sources:** - Surveys - Location information - Physical activity - Smartphone usage ## Research Team **Tarun Katapally, Ph.D.** Assistant Professor Johnson Shoyama Graduate School of Public Policy University of Regina --- sidebar_position: 8 --- # Changing Buildings, Changing Behavior Changes to the built environment can create barriers to mobility. Changes can range from large-scale closures of roads or rail stations to smaller short-term changes in local environments. The University of Saskatchewan is characterized by a series of walkways and tunnels which connect buildings on campus and allow students and employees to move across campus without being exposed to the harshness or variability of winter. In the Fall of 2016, a critical walkway connecting the Departments of Agriculture, Engineering, and the main student parking lots was removed to accommodate the construction of a new building. The removal constitutes a natural experiment in the change in mobility for individuals forced to change behavior based on a change in the built environment. Leveraging WIFI-based indoor localization and GPS, the dynamics of adaptation can be studied. ## Study Profile **Participation duration:** 5 weeks **Sample size:** 117 subjects **Data sources:** - Surveys - Location information - Physical activity ## Research Team **Scott Bell, Ph.D.** Professor, Department of Geography and Planning University of Saskatchewan --- sidebar_position: 9 --- # Walking, Riding, and the Weather Walking behavior in urban centers is a complex interaction between the built environment, the accessibility of mass transit, the personality of the individual, and the weather. Over a four-week period of highly variable weather, participants in Saskatoon, Saskatchewan recorded activity patterns and locations and reported use of public transit. By comparing these results with publicly available weather data for the period and published neighborhood walkability indices, models of the interactions between built environment, transit, weather, and personality can begin to be explored. ## Study Profile **Participation duration:** 5 weeks **Sample size:** 84 subjects **Data sources:** - Surveys - Location information - Physical activity ## Research Team **Scott Bell, Ph.D.** Professor, Department of Geography and Planning University of Saskatchewan **Kevin Stanley, Ph.D.** Associate Professor, Department of Computer Science University of Saskatchewan --- sidebar_position: 10 --- # Opportunistic Analysis of a Mobile Fad Monitoring subjects in the wild not only allows targeted instrumentation of populations to answer specific research questions, it also allows researchers to investigate emergent phenomenon within the subject pool as the emerge as opportunistic natural experiments. During the summer of 2016, a population was under study for mobility patterns throughout the city when the Pokémon Go craze hit. A third of the participants reported playing Pokémon Go, and visible changes in activity patterns and mobility patterns were evident in the week following its launch. These changes quickly petered out providing an unprecedented glimpse of the impact of a technological fad on human behavior. ## Study Profile **Participation duration:** 4 weeks **Sample size:** 65 subjects **Data sources:** - Surveys - Location information - Physical activity behavior ## Research Team **Kevin Stanley, Ph.D.** Associate Professor, Department of Computer Science University of Saskatchewan --- sidebar_position: 11 --- # Social Isolation and Schizophrenia People with schizophrenia are often more socially isolated than the general population. This is important, because social isolation and loneliness are known to be health risk factors, and can increase mortality risk. In addition, research has shown that social isolation is related to how well people with schizophrenia function in the community. While people with schizophrenia are more socially isolated than the general population, they often report wanting to have more social connections. In this pilot study, we investigated this disconnect between what people with schizophrenia participants report (wanting more social interactions), with what they are doing in their daily lives. People with and without schizophrenia were recruited and were asked to carry a study cell phone, with the Avicenna app enabled. Study cell phones were utilized as not all people with schizophrenia own smartphones. In addition to assessing social isolation and the desire for social contact we also were assessing the feasibility of Avicenna, given that people with schizophrenia were often unfamiliar with smartphone app use. Over seven days participants were prompted with several questions (four times per day) about their desire for social interactions, and the quality of interactions that occurred. In addition, we assessed GPS, Bluetooth, accelerometer, and ambient audio recordings of participant daily life. These data allowed for passive data collection which can help us identify which participants are more socially isolated, and how that data may differ from self-reported social isolation. In this pilot study, participants found the Avicenna app easy to use and non-intrusive to their daily activities. We have begun to analyze the cell phone objective data to identify key differences in our participant groups. ## Research Team **David Gard, Ph.D.** Professor of Psychology San Francisco State University **Daniel Fulford, Ph.D.** Assistant Professor Department of Occupational Therapy Boston University --- sidebar_position: 12 --- # Exploring New Technologies for Foodborne Disease Studies tracking the source of foodborne outbreaks traditionally involve telephone interviews several days after illness onset and can be adversely affected by participant recall. This project evaluated Avicenna as a new technology for gathering data on food consumption and the occurrence of gastrointestinal illness. This pilot study provided a unique opportunity to measure the extent of participant recall bias and the resulting limitation of current investigation strategies. University students were recruited for a project to determine the utility of Avicenna. Students are a good target population, as most have smartphones and frequently use them for data sharing and communication. Students are also often challenging to recruit using current interview methods. Further, many are learning to cook, or eat out frequently, elevating their risk for foodborne disease. Over a 10 week period, participants were asked to report any gastrointestinal symptoms using Avicenna. During the first 10 days, participants were also asked to take photos and answer 3 times daily surveys on recent food choices. Participants reported whether they were eating in restaurants or take-out food. The Avicenna app linked participant data to location. Participants also completed an online survey either 1 or 2.5 weeks after day 5 asking them to recall their food choices for days 2 to 8. By comparing the survey with the Avicenna, the extent of recall bias was assessed. This proof of concept study also examined the feasibility of using Avicenna to support the investigation of enteric illness and inform dynamic simulation models of outbreak detection. Using participants’ reported experiences with the system, the project identified hurdles to scaling up the use of Avicenna to a larger, more diverse study population and to applying this technology to other questions not sufficiently answered using traditional survey techniques. ## Study Profile **Participation duration:** 10 weeks **Sample size:** 100 subjects **Data sources:** - Surveys - Location information - Physical activity behavior ## Research Team **Cheryl Waldner, Ph.D.** Professor, Epidemiology Large Animal Clinical Sciences University of Saskatchewan --- sidebar_position: 13 --- # Project SNAP While the health burdens associated with tobacco are decreasing for society as a whole, they fall increasingly disproportionately on lower-income and some minority populations. Evidence suggests that exposure to tobacco use among members of a person’s social network and the cumulative effects of that person’s exposures to tobacco-related messaging, both encouraging and discouraging use, can strongly impact that person’s tobacco behaviors. While of great importance, such effects can be difficult to measure with traditional measures, due to the difficulties of assessing the occurrences of specific influences and exposures, and of tobacco-related behaviors, knowledge, and ideation. Within this study spanning two low-income communities in the United States, Avicenna Health is being used to address such challenges by using high temporal resolution evidence gathered via smartphones to study the impact of pro- and anti-tobacco messaging in online and traditional media on tobacco use, and of in-person exposure to tobacco use in others. Participants were recruited via respondent-driven sampling on the basis of reported friends; the study further used this friendship relation to automatically detect (using on-phone Bluetooth technology) cases in which a participant was in close proximity to the friend. To monitor message exposure, the system made use of communicational monitoring, on-device self-reporting, and sensor data. To capture exposure to online messaging, Avicenna Health monitored participant browsing to webpages containing certain tobacco-related keywords, as well as other randomly selected page visits. To capture understanding of placement of and exposure to other messaging, participants were asked to indicate encounters with and photograph messaging which they encountered, using a study-specific button in the Avicenna Health-provided interface. The system then enquired about the participant’s reaction to the images, and the images submitted via such mechanisms were automatically geotagged with the location where they were taken, as is typical with all questions and other data collected by Avicenna Health. Questionnaires were triggered by proximity to personal contacts as well as occurrence of browsing, as well as at random times during the day (such as to sense tobacco use by the participant and others). ## Study Profile **Participation duration:** 10 weeks **Sample size:** 100 subjects **Data sources:** - Surveys - Location information - Contact pattern - Physical activity behavior - App usage statistics - Internet browsing behavior ## Research Team **Kasisomayajula Viswanath, Ph.D.** Lee Kum Kee Professor of Health Communication Harvard T. H. Chan School of Public Health (HSHP) Dana-Farber Cancer Institute (DFCI) # Frequently Asked Questions ## What are the main differences between trial and full-license studies? Here are the key differences between the two license types: - The trial version is free of charge, allowing full access to the default features without any restrictions. - The trial version is intended only for test purposes. This setup is ideal for researchers to explore whether Avicenna meets the needs of their projects without financial commitment. If you plan to conduct actual field research with real participants, upgrading to the full license is necessary. - In the trial version, the collected study data is wiped monthly, and the study will be deleted after one year. This is to ensure optimal service for ongoing licensed studies. All data deletions are communicated well in advance via email to give researchers enough time to secure their data. To upgrade your study from Trial to Licensed, you can contact us directly via email at [support@avicennaresearch.com](mailto:support@avicennaresearch.com) and send your study ID. --- ## How study data is uploaded? The Avicenna app automatically uploads the collected data when there is an Internet connection available. By default, Avicenna uses any Internet connection (mobile or Wi-Fi), but you can change this for your study and set it to use Wi-Fi only. Participants can also change this setting anytime on their phone via the "Upload via Wi-Fi only" option. The data appears on the website as soon as they are uploaded from the phone. --- ## Can participants stop data collection? Yes. Avicenna provides participants with a few different ways to stop the data collection any time they want, either permanently or temporarily. If you want participants to be able to permanently disable a data source, but still be part of the study, you can set that data source to optional. This instructs the Avicenna app to give participants the option to opt out of this data source if they choose to. Participants can also temporarily disable data collection at any time by going to the app and pressing "Pause Participation". This will stop all automatic data collection for one hour. The data collection will resume automatically after one hour. Note that participants will continue to receive surveys during this time if there are any surveys scheduled. --- ## Is Avicenna Research ISO 27001:2022 and GDPR Compliant? Yes. Please check [our Security and Compliance documentation](reference/security-and-compliance#meeting-gdpr-standards). --- ## How many questions can I have per survey? As many as you need. There is no limitation on the number of questions you can have in your survey. But keep in mind if you plan to ask the survey periodically, having many questions can negatively impact the response rate. --- ## How can I access data from my study? When you log in to Avicenna with your Researcher account, Avicenna will take you to the Researcher Dashboard, where you can have access to all the data collected for your study. You may choose to export the data in different formats or explore them directly via the dashboard. Researcher Dashboard provides a few data visualizations mostly aimed at adherence monitoring. You also have access to a few web-based data analysis tools such as Kibana. If you need to perform more in-depth analysis, you can simply export data in your desired format. --- ## How long participants can remain offline while in a study? When Avicenna captures data from the participant's device, it encrypts the data and stores it on the phone as long as necessary. The data will be removed only when they're uploaded to the servers. Suppose a given participant does not have an Internet connection for an extended period. In that case, the data accumulates on their phone, and as soon as a connection is available, the data is uploaded. There are two pitfalls to be aware of here. First, when a large amount of data is stored on the device and not uploaded yet, the chance of losing all the data because of phone hardware issues increases. The person might lose the phone or break it, and in that case, all buffered data are lost. Also, if a large amount of data is buffered on the device, the device might run out of space to record new data. This is particularly a problem with low-end older phones that have smaller memory. So while the app does it's best not to lose any data, it's always good to make sure the data is received from all participants regularly. --- ## Can I access the name and email address of the participants in my study? Yes. If you are the study owner, you can [show participants' PII on the Participation page](./reference/study-setup-and-deployment/participation.md#show-participants-personally-identifiable-information-pii). --- ## What happens if my participant changes her timezone? Avicenna keeps track of the participant's timezone, and if they travel long enough that their timezone changes, Avicenna automatically reschedules all surveys and study settings based on the new timezone. Keep in mind that the timezone change is received from the participant's smartphone or browser. --- ## How much storage does having the Avicenna app take up on a phone? The exact storage the Avicenna app takes varies depending on the phone type and manufacturer, but it is approximately 70 to 100 megabytes. For example, on most Android devices, the app approximately uses 65 Mb after installation. However, like any other app, as you continue to use this app, the storage used gradually increases as well. Keep in mind that the amount of this storage consumption is based on the studies you are participating in. --- ## Does having the Avicenna app on your phone impact your data plan limits? The Avicenna app uses the Internet to download and upload data from your studies. As long as possible, the app uses available Wi-Fi, but if no Wi-Fi connection exists, the app falls back to using the data plan. The amount of data that the Avicenna app will use depends on your study configuration. For example, if the study uses sensor data sources more data is used compared to studies that only contain surveys or cognitive activities. --- ## I entered my Criteria, but the survey is not being triggered as expected. What could be wrong? Check that your syntax is correct, the IDs are accurate, and the conditions are logical. Remember that only numerical responses can be used in Criteria. --- ## Can I use Criteria to control the flow of surveys within a larger study? Yes, Criteria is an excellent tool for controlling the flow of studies and directing participants through different survey paths based on their responses. --- ## How can I stay updated about Avicenna's latest changes? If you want to stay informed about Avicenna's updates, including new features, improvements, resolved bugs, etc., there are four ways to do so: 1. Regularly check the [Avicenna Blog](https://avicennaresearch.com/blog) for our monthly release notes. 2. Visit the [Avicenna Forum](https://forum.avicennaresearch.com/c/release-notes/6) for weekly release notes. 3. If you have an Avicenna researcher account, check the `What's New` section under the _Resource Hub_ on your dashboard. 4. Follow [Avicenna's LinkedIn page](https://www.linkedin.com/company/avicennaresearch/). --- ## How can I check the operational status of Avicenna services? Our Service Status page provides real-time updates and information on the operational status of various services like Avicenna dashboards, Avicenna APIs, and our File & Data Server. Additionally, you can view stats for Overall Uptime (percentage values) over different periods, such as the last 90 days, and access historical data using the Calendar View link. You can also access the Service Status page via its link located under the Resource Hub on your researcher dashboard. If you encounter any issues with Avicenna services, please check the Service Status page first to see if there are any known outages. If there's none, you can contact our support team for further assistance. Besides manually checking the page, you can also subscribe to updates on service status. To do so, open the Service Status page and click on the bell button in the top right corner. Enter your email address to receive email notifications every time Avicenna publishes an update. --- ## How can I rapidly deploy similar studies (with minor differences)? Avicenna provides three rapid deployment methods for duplicating and adapting study components: - [Create a full copy of an existing study's protocol.](./reference/study-setup-and-deployment/create-a-new-study.md#duplicating-a-study) - [Duplicate and then move specific activities between studies.](./reference/activities/README.md#accessing-activities) - [Share surveys across studies using portable JSON definition files.](./reference/surveys/README.md#versions-import-and-export) --- ## Some activity sessions are lost. What can I do now? You can [create](reference/activities/activity-sessions#creating-a-session) or [release](reference/activities/activity-sessions#releasing-an-activity) new sessions manually to fill the gap. --- ## I created a participant account with my email address, but I want to be a researcher now. How can I do that? Avicenna doesn't support switching between account types. However, you can change the email address associated with your participant account (from `Settings` > `Account Information`) and use the previous email address for your researcher account. Also, you can [delete your participant account](reference/study-setup-and-deployment/account-deletion.md) if you're fine with waiting. Then, you can use the corresponding email address for your researcher account. --- ## How can I delete my researcher account? To delete your researcher account, please contact our support team at [support@avicennaresearch.com](mailto:support@avicennaresearch.com). In your email, include your account details and explicitly state your request to delete your researcher account. For security reasons, we cannot process account deletion requests through other channels or without proper verification of your identity. :::danger - Account deletion is permanent and cannot be undone. - Any studies you own need to be [transferred to another researcher](reference/study-setup-and-deployment/roles-and-permissions.md) or deleted before account deletion. - All personal information associated with your account will be deleted according to [our data retention policies](https://avicennaresearch.com/legal#privacy-policy). ::: --- ## I deleted a participant from my study. How can I restore their data? Contact our support team at [support@avicennaresearch.com](mailto:support@avicennaresearch.com) as soon as possible. Include your study ID and the participant ID in your email. Please note: - We maintain backups of study data, but restoration is a complex process that requires manual intervention from our technical team. - The restoration process is **not guaranteed to recover 100% of the data**, especially if significant time has passed since deletion. **To prevent accidental deletions in the future**: - Filter participants to make the list shorter before deletion. - Assign appropriate [roles and permissions](reference/study-setup-and-deployment/roles-and-permissions.md) to the researchers to limit who can delete participants. **To make the accidental deletion less severe**, download the participation data regularly. ---