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 Ethica app explicitly requested the user's location and received it from GPS satellites.
  • Network: means the Ethica app explicitly requested the user's location and received it from nearby cell towers and Wi-Fi access points (only in Android) (technical details).
  • GPS-Passive: means other apps running on the participant's device requested location from GPS satellite, and Ethica 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 Ethica received a copy as well (only in Android).
  • 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.

This is internally stored as 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 Ethica 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, Ethica 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. Also, the missing permission is reported via Audit Log code 300.

If the participant choose "grant permission once," Ethica is allowed to collect GPS data for a limited time, likely for one or two days. This period is determined by the Android or iPhone operating system. After this period, the permission is automatically revoked by the operating system, and Ethica will ask the participant for the permission again. The second time Ethica asks the participant for the GPS permission, in addition to the 3 options listed above, participant will have a fourth option, "Allow Always". Choosing this option grants Ethica with 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, or turn off their device’s GPS (accessible from the home screen of most smartphones), or simply terminate the Ethica app. In all of these cases, Ethica 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 in the Participation Page of the Researcher Dashboard. At any time, Participants can turn on their GPS, or grant the missing permissions, or restart the app. Each of these events will resume the data collection in Ethica 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 participant's battery rapidly. To reduce this impact, GPS data source in Ethica 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.

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 Ethica 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, Ethica uses motion-based activity recognition (MBAR) and Wi-Fi data.

In both Android and iOS, Ethica considers the participant as stationary if all of the following conditions are met since the last cycle:

If both of the above are True, the app assumes the device has been stationary during the last cycle.

In addition to MBAR data, Ethica on Android uses Wi-Fi data as well. Based on Wi-Fi data, Ethica 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 pervious 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 has at least 30% similarity.

If all of the above 3 conditions are met, Ethica for Android concludes that Wi-Fi data suggest the participant has been stationary.

Now, in each cycle, the Ethica 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, Ethica 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), and 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, Ethica 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 granted the necessary permissions. Otherwise, no data for MBAR or Wi-Fi will be available to the Ethica's GPS component, and the app will record a fresh GPS data each cycle.

Passive Data Collection in Android

Android allows apps to listen for GPS records passively. It means an app like Ethica 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 Ethica holds required permissions to collect GPS data). This way, Ethica can collect GPS data without causing additional battery consumption.

Note that this behaviour does not interfere with Ethica's periodic GPS data collection. Ethica collects GPS data periodically. The provider in this case is set to gps, network, or gps-reuse. It additionally also listens and records GPS records requested and received by other apps. The provider in this case is set to gps-passive or network-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, Ethica receives every GPS record requested by the 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 worths mentioning that while GPS records collected by Ethica are still collected in 5-minute intervals, you might find passive GPS records captured between intervals as well.

Wi-Fi

Supported in Android.

Monitors Wi-Fi signals in the surrounding environment. This data source scans different frequency channels and records 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 primary 20 MHz 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, also known as the RSSI. Internally stored as level.