Context Sampling Package

Collect location, activity, geofence, mobility, weather and air quality data in a CARP Mobile Sensing study.

carp_context_package adds six context measures to a CARP Mobile Sensing (CAMS) study: location, physical activity, geofence events, mobility features, weather and air quality. Use it to study where participants go, how they move and what their environment is like.

The package builds on the location, activity_recognition_flutter and mobility_features plugins. Weather comes from OpenWeather and air quality from the World Air Quality Index (WAQI) project; both services need an API key.

pub.dev

API reference

GitHub

Precise location required

Every measure except ACTIVITY collects data only when the participant grants location access with precise location. LOCATION also needs location access all the time, and on Android so do GEOFENCE and MOBILITY. See Permissions and background.

Features

Location

Location fixes from the phone's location service, continuously or once per trigger. One LocationService sets the accuracy, distance and interval for the study.

Activity recognition

Still, on-foot, walking, running, cycling and in-vehicle events from the phone's activity recognition, each with a confidence of at least 50%.

Geofences

Enter, dwell and exit events for circular geofences. The events can trigger other tasks in the protocol.

Mobility features

Daily stops, moves, places, home stay, location entropy and distance traveled, computed on the phone.

Weather

Current weather at the phone's position from OpenWeather, collected once per trigger.

Air quality

The air quality index of the WAQI station nearest to the phone, collected once per trigger.

Measure types

The package provides six measure types in the dk.cachet.carp namespace:

Measure type	Data	Android	iOS
`dk.cachet.carp.location`	Location fixes from the phone's location service	Yes	Yes
`dk.cachet.carp.activity`	Recognized physical activity and its confidence	Yes	Yes
`dk.cachet.carp.geofence`	Enter, dwell and exit events for one circular geofence	Yes	Yes
`dk.cachet.carp.mobility`	Daily mobility features computed from location	Yes	Yes
`dk.cachet.carp.weather`	Current weather from OpenWeather	Yes	Yes
`dk.cachet.carp.airquality`	Air quality index from WAQI	Yes	Yes

WEATHER and AIR_QUALITY are one-time measures, and the other four are event-based. For the difference, see Event-based and one-time measures. Each measure's page documents its configuration, platform differences and data fields.

Requirements

Component	Requirement
Dart SDK	3.10 or later
Flutter	3.44 or later
`carp_mobile_sensing`	2.4.0 or later
Android	API level 26 (Android 8.0) or later, with Google Play services for activity recognition
iOS	15.0 or later, built with Swift Package Manager
API keys	An OpenWeather API key for weather and a WAQI token for air quality

See Installation for the platform setup.

How it works

The six measures run on four devices in the protocol: the phone itself and three services, which CAMS treats as connected devices of the phone:

flowchart LR
    Phone["<b>Smartphone</b><br/>primary device<br/>that runs activity"]
    Location["<b>LocationService</b><br/>location, geofences<br/>and mobility"] --> Phone
    Weather["<b>WeatherService</b><br/>weather from<br/>OpenWeather"] --> Phone
    AirQuality["<b>AirQualityService</b><br/>air quality<br/>from WAQI"] --> Phone
    Phone --> Endpoint[("<b>Data endpoint</b><br/>stores the<br/>measurements")]

Smartphone: the primary device. It runs ACTIVITY itself and collects the measurements of all four devices.
LocationService: gives the phone's location to LOCATION, GEOFENCE and MOBILITY, and sets the accuracy, distance and interval that all three share.
WeatherService and AirQualityService: hold the API keys of the two web services and run WEATHER and AIR_QUALITY.
Data endpoint: stores the measurements, as in any CAMS study.

In the protocol, add each service as a connected device of the phone, and target each task at the device its measures run on. See Services.

Next steps

Installation

Add the package to a CAMS app and configure Android and iOS.

Quickstart

Build an app that collects activity, location and mobility features.

Services

The three services, their settings and how they connect.

Permissions and background

The permissions each measure needs and how collection continues in the background.