Location

[mojtaba]

GPS

Supported in Android & iOS.

Download Sample Data

This data source measures the location of the device using GPS sources.

Use Cases

• Environmental health studies: Linking a participant’s location data with external environmental factors like air pollution, noise levels, and access to green spaces to study their impact on health
• Behavioral and lifestyle research: Analyzing daily mobility patterns and time spent in various locations (e.g., home, work, social settings) to understand routines, social engagement, and sedentary behavior
• Public health and epidemiology: Using anonymized and aggregated location data to model the spread of infectious diseases or to study travel patterns during a public health crisis

Data Structure

Besides the common data fields, 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. Internally stored as a provider. 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. Internally stored as gps.
  • Network (only in Android): Means the Avicenna app explicitly requested the user’s location and received it from nearby cell towers and Wi-Fi access points. For more technical details, check here. Internally stored as network.
  • Fused (only in Android): Means the Avicenna app is using a location API of Google Play service named the Fused Location Provider API. This API intelligently combines different signals to provide location information. Internally stored as fused.
  • GPS-Passive (only in Android): Means other apps running on the participant’s device requested location from the GPS satellite, and Avicenna received a copy as well. Internally stored as gps-passive.
  • Network-Passive (only in Android): 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. Internally stored as network-passive.
  • Fused-Passive (only in Android): Means other apps running on the participant’s device requested location from the Fused Location Provider API, and Avicenna received a copy as well. Internally stored as fused-passive.
  • 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 provided by GPS satellites are reused. Internally stored as gps-reuse.
  • 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 nearby cell towers and Wi-Fi access points (network provider) are reused. Internally stored as network-reuse.
  • 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 Location Provider API are reused. Internally stored as fused-reuse.
• 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. Internally stored as speed.
• Bearing: The horizontal direction in which the device is facing or moving at the time of this record, measured in degrees from true north (0° to 360°). Internally stored as bearing.
• Accuracy: The accuracy of this reading, in meters. The closer to 0, the more accurate. 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. Additionally, location services must be enabled to obtain location information. Participants will have the following options:

• Don’t Allow: If the Participant declines this permission, 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.
• Allow While Using App: Same as above; Avicenna will not collect GPS data when the app is closed.
• Allow Once: If the participant chooses this option, Avicenna is allowed to collect GPS data for a limited time, likely for one or two days. This period is determined by Android or iOS operating systems. After this period, the permission is automatically revoked by the operating system, and Avicenna will ask the participant for permission again.
• Allow always: The second time Avicenna asks the participant for the GPS permission, in addition to the 3 options listed above, the participant will have this option. Choosing Allow Always grants Avicenna permanent permission to access GPS data, until it’s revoked by the participant explicitly.

GPS Permission Request on iOS

GPS Permission Request on Android

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 location services (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 the missing data will be visible to the researchers on the Participation Page 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.

Adding GPS As a Data Source

See Adding Data Sources.

Data Collection Behavior

Compared to other data sources, monitoring GPS requires considerable power and can drain a participant’s device battery rapidly. To reduce this impact, the GPS data source in Avicenna uses 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, explained below, 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 (MBAR) and Wi-Fi data.

In both Android and iOS, Avicenna considers the participant as stationary, and assumes the device has remained stationary during the last cycle 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 in iOS and 100% Confidence in Android).
• All MBAR data indicate the phone has been stationary (CMMotionActivity.stationary in iOS and STILL or TILTING in Android).

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 networks set for the current cycle and the previous cycle have at least 30% similarity.

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:

{
  "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 is 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, meaning an app like Avicenna does not have to actively request fresh GPS records. Instead, it can receive a copy of GPS records requested by other apps, given that Avicenna has the necessary permissions. This allows Avicenna to collect GPS data without causing additional battery consumption.

This passive behavior does not interfere with Avicenna’s periodic GPS data collection. Avicenna still collects GPS data at regular intervals, with providers set to gps, network, fused, gps-reuse, network-reuse, or fused-reuse. In parallel, it also listens for GPS records requested by other apps, recorded under providers such as gps-passive, network-passive, or fused-passive.

For example, if a participant is navigating from Point A to Point B using Google Maps for one hour, Avicenna will receive and record every GPS record requested by Google Maps as passive data. During this time, it will also collect periodic fresh GPS data, as the participant is actively moving.

While Avicenna collects its own GPS records in 5-minute intervals, passive GPS records may also appear between those intervals.

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 noise, and extract kinematic features from the GPS data source. If you need unprocessed data for your study, see Raw Data. Then, it predicts the mobility mode of GPS data points using the extracted features. Here, we first define the terminology 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 where 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 fewer than 5 data points are skipped with mobility_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 into one of the 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/s², calculated by our feature extraction algorithm . Internally stored as acceleration_fe.
• Jerk-Feature Extraction: The jerk of this record, in m/s³. 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, is calculated by our feature extraction algorithm. Internally stored as bearing_rate_fe and measured in degrees per second (°/s).
• Segment ID: Unique identifier of a GPS segment in a GPS trajectory. Internally stored as segment_id. 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) was predicted by our machine-learning model. Internally stored as mobility_mode.

Monitoring and Exporting GPS Data

You can monitor and export GPS data using either the Data Export page or Kibana.

GPS Data Source in the Participant App

To use this data source, follow the platform-specific instructions below.

Android

Follow these steps to grant GPS data collection permissions on Android:

1. Open the Avicenna app and go to the study setup banner. A message will appear saying GPS permission is required. Tap GRANT GPS ACCESS.

   

2. A system message will appear asking for location access:

   
   • Do not select DON’T ALLOW. As explained in the Required Permissions section, the app will not be able to collect location data.
   • If you select WHILE USING THE APP or ONLY THIS TIME, you will receive another prompt that takes you to the app’s Settings.

[!note]
Make sure Precise Location is selected to ensure accurate data collection.

4. Tap Open Settings.

   

5. In the settings, select Allow all the time so the app can collect GPS data continuously.

   

iOS

Follow these steps to grant GPS data collection permissions on iOS:

1. Open the Avicenna app and go to the study setup banner. A message will appear saying GPS permission is required. Tap CONTINUE.

   

2. A system message will appear asking for location access:

   
   • Do not choose Don’t Allow. As explained in the Required Permissions section, this will prevent the app from collecting location data.
   • Do not choose Allow Once. This will only give temporary access.
   • If you choose Allow While Using App, you will see another prompt.

3. Tap Change to Always Allow to give the app full background location access.

   

Alternative method:

You can also update this setting manually in your device’s Settings app:

1. Open Settings and go to Apps.

2. Select Avicenna.

3. Tap Location.

   

4. Select Always and make sure Precise Location is enabled.

   

---

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.

Use Cases

• Environmental health studies: Studying exposure to Wi-Fi networks and radiofrequency electromagnetic fields in relation to health outcomes
• Social and behavioral research: Identifying travel patterns and adherence to daily routines based on network changes

Data Structure

Besides the common data fields, each GPS record includes the following:

• RSSI (Received Signal Strength Indicator): The detected signal strength in dBm, internally stored as level.
• 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.

Adding Wi-Fi As a Data Source

See Adding Data Sources.

Data Collection Behavior

Android devices collect Wi-Fi data in the following steps:

• Android asks the operating system (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 with 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 the 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.

Monitoring and Exporting Wi-Fi Data

You can monitor and export Wi-Fi data using either the Data Export page or Kibana.

Wi-Fi Data Source in the Participant App

If Wi-Fi is turned off on your device, you’ll see this message in the app’s setup banner. If Wi-Fi is on, this message will not appear. Please turn on your Wi-Fi so the app can continuously collect data.