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 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 you can learn more about the specifics of this page. At the end, our page setting should look like the following image:

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

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:

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:

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.