Links

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 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).
  • Fused: means the Ethica 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 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).
  • Fused-Passive: means other apps running on the participant's device requested location from fused location provider API, and Ethica 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 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 chooses "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 Android or iPhone operating systems. After this period, the permission is automatically revoked by the operating system, and Ethica will ask the participant for permission again. The second time Ethica 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 Ethica 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 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 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 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 a participant's battery rapidly. To reduce this impact, GPS data sources in Ethica 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
Ethica starts collecting fresh GPS records every 5 minutes. Ethica 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 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 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, 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), 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 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 been granted the necessary permissions. Otherwise, no data for MBAR or Wi-Fi will be available to Ethica'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 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 behavior 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, 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, Ethica 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 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 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.
  • Ethica puts each SSID in one record.
After getting the first batch of SSIDs, Ethica 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, Ethica will get a lot of records for its SSID (often with slightly varying levels of RSSI). But if a network is far, Ethica collects fewer records, because OS will see this network less often in its scans.
Note that Ethica collects data points with different RSSI levels, frequencies, and BSSIDs for the same SSID and the same record time.