Background Sensor Data

Viewing, filtering, downloading and preprocessing the sensor files on the study's Sensors tab.

Open a study and select the Sensors tab in the row of study sections. The page is headed Sensor Data Files. It lists the files that the SMAAT app uploads in the background, independently of surveys. Each file (record) belongs to one participant and one sensor stream and covers a period between its first and last timestamp.

The tab is available to the study author and to project collaborators with data access (see Projects and collaboration). Which streams are recorded is set in the Study Builder under Protocol → Background Data (see Sensor Data).

What appears on the Sensors tab

GPS: background location samples, each with latitude, longitude, timestamp and accuracy (in metres).
Health data: one file per metric read from Apple Health (iOS) or Health Connect (Android), for example steps, restingHeartRate and sleep. The sensor column shows the metric name.
Task audio: audio recorded by cognitive tasks, labelled “Task audio” with the note “Cognitive-task recording”.

Note: motion and environment sensors that are recorded while a survey is open (accelerometer, gyroscope, magnetometer, barometer, light sensor, device motion) are stored with the survey response. They appear in the response exports on the Data tab, for example in the AccelerometerData column (see Data Overview), and not on this page.

Table columns

The table shows, for each file: a selection checkbox, Sensor, Unit / Platform (the unit of the stream and the operating system and version of the phone, for example “deg,m,m/s · ios 18.2”), Participant Code, File Size (bytes), First Timestamp, Last Timestamp, Encrypted and a Download button. Selecting the Sensor, Participant Code, File Size, timestamp or Encrypted heading sorts the table by that column.

Sensor Data Files page with the Download All Data, Download Filtered Data, Remove Selected and Preprocess Data buttons, the filters, and a table of GPS and health-data files with unit, participant code, file size and timestamps. — The Sensors tab: action buttons, filters and the list of background sensor files per participant.

Filtering sensor files

The Filters card narrows the table:

By Sensor: one or more streams. The options are the streams present in the study's data.
By Participant: one or more participant codes.
From and Until: a date and time range. A file is shown when its first timestamp is after From and its last timestamp is before Until.
A select box sets the number of files per page (5 to 100).

Example: Choose GPS under By Sensor and three participant codes under By Participant to list only the location files of those participants.

Troubleshooting tip: if files are missing for a participant, check the permission status shown on the participant's page (Participants tab → participant) and whether the stream is enabled under Background Data in the Study Builder.

Downloading and deleting files

Each file downloads as a separate JSON file named <participant code>_<first timestamp>.json that contains an array of samples. Task audio downloads as an audio file named <participant code>_<question ID>_<trial>.m4a (or the extension of the recorded format).

Download in a row saves that file.
Download All Data saves every file of the study, one file at a time, and Download Filtered Data saves the files that match the current filters. A Downloading Files dialog shows the progress.
Remove Selected deletes the ticked files after a confirmation. Deletion is permanent and only the study author can delete files.

Encrypted files: the Decryption card appears when files were encrypted on the phone. The Encrypted column names the encryption of each file, and the card shows the step for each kind of file in the study:

End-to-end encryption: select Decrypt data. If your encryption vault is locked, select Unlock vault to decrypt first. No key file is needed. Collaborators can decrypt only after the author has shared the study key with them.
Self-managed study key: select the key file under Private Keys (.pem files) and press Decrypt Now.
Server-side encryption: the files are stored readable and there is no decryption step.

The files are decrypted in the browser, and the download buttons and Preprocess Data use the decrypted content. An end-to-end encrypted file that has not been decrypted yet is decrypted when you download it or open it in Preprocess Data. Task-audio recordings are decrypted when you download them.

Preprocess Data viewer

Tick one or more files in the table and select Preprocess Data. The Preprocess Data dialog loads the samples of the selected files (task audio has no samples and is skipped) and offers three views.

Table: one row per sample, with participant code, sensor and the sample fields. Filter the rows by participant and by a From/Until time range, and tick the rows to keep. Download Preprocessed Data saves the ticked rows as a CSV file. The Map and Analysis views use the same ticked rows.
Map: the GPS samples among the ticked rows as points on a map, connected as a route (“GPS Route Map”).
Analysis: groups GPS samples into places. Samples within the Cluster Radius (meters) (default 500) belong to one place, and consecutive samples further apart in time than the Time Gap (hours) (default 1) do not count as the same visit. The result table lists, per participant and place, the location name, latitude, longitude, time spent (hours) and total distance travelled (km). Download Aggregated Data saves the table as a CSV file.

Third-party services: the Analysis view looks up a place name for each cluster by sending the cluster's latitude and longitude from your browser to the public OpenStreetMap Nominatim service. The lookup starts when the Analysis view opens. The Map view loads its map tiles from OpenStreetMap servers. If your ethics approval or data protection agreement does not allow location coordinates to be shared with third parties, do not open these two views; use the Table view or the JSON downloads and analyse the coordinates offline.

Example: To estimate time spent at home and elsewhere for one participant, filter the table to that participant and GPS, select the files of one week, open Preprocess Data and switch to Analysis with a cluster radius of 200 m.

Next Steps

Related pages on sensor data:

Sensor DataConfigure which sensors and health metrics a study records.Sensor heterogeneityUnits, device metadata and differences between phones.Data OverviewSurvey responses and the sensor data recorded during surveys.Frequently Asked QuestionsAnswers to common questions about the SMAAT platform.