Surveys

A Survey is a type of Activity 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, Notification Templates, and Criteria. 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 which is basically a plain-text JSON document. The file describes when the Survey should be prompted (the Triggering Logics), how the participant should be notified (the Notification Templates), what enables or disables a Survey (the Criteria), 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. 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.

   

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

   

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 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. 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:

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:

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

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:

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:

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

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.

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 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 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 instructs Avicenna to show the participants how many questions are left to answer in the current Survey session. The following picture shows the same Survey, with and without the Show Progress option enabled:

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:

Show Previous Button Enabled	Show Previous Button Disabled