SmartphoneStudyProtocol class
A study protocol that runs on a smartphone.
A protocol says what to measure and when. It holds the primary device
(PrimaryDeviceConfiguration) that collects data, the connected devices
(DeviceConfiguration), and the task controls (TaskControl) that pair a
trigger with a task. CAMS adds a studyDescription, a dataEndPoint that
says where data goes, and a privacySchemaName.
You build one in code (or load it from JSON) and add it with
SmartPhoneClientManager.addStudyFromProtocol.
Key points:
- The first device added with addPrimaryDevice is the phone running the study.
addTaskControlpairs oneTriggerConfigurationwith oneTaskConfiguration.- Adding a device also adds a
MonitoringTaskthat collects errors and triggered and completed tasks from that device. - Serializes to JSON, so the same protocol can be deployed from a server.
- SmartphoneStudyProtocol.local creates a ready-to-use local protocol.
See also SmartphoneDeployment, which is created from a protocol, and SmartphoneDeploymentExecutor, which runs it.
// Create a study protocol storing data in a local SQLite database.
SmartphoneStudyProtocol protocol = SmartphoneStudyProtocol(
ownerId: 'abc@dtu.dk',
name: 'Track patient movement',
dataEndPoint: SQLiteDataEndPoint(),
);
// Define which devices are used for data collection.
// In this case, its only this smartphone.
Smartphone phone = Smartphone();
protocol.addPrimaryDevice(phone);
// Automatically collect step count, ambient light, screen activity, and
// battery level. Sampling starts immediately.
protocol.addTaskControl(
ImmediateTrigger(),
BackgroundTask(measures: [
Measure(type: SensorSamplingPackage.STEP_COUNT),
Measure(type: SensorSamplingPackage.AMBIENT_LIGHT),
Measure(type: DeviceSamplingPackage.SCREEN_EVENT),
Measure(type: DeviceSamplingPackage.BATTERY_STATE),
]),
phone,
);
- Inheritance
-
- Object
- Snapshot
- StudyProtocol
- SmartphoneStudyProtocol
- Mixed-in types
- Annotations
-
- @JsonSerializable.new(includeIfNull: false, explicitToJson: true)
Constructors
- SmartphoneStudyProtocol({String? ownerId, required String name, String? applicationName, StudyDescription? studyDescription, DataEndPoint? dataEndPoint, String? privacySchemaName})
-
Creates a new SmartphoneStudyProtocol with a unique
name. -
SmartphoneStudyProtocol.fromJson(Map<
String, dynamic> json) -
factory
-
SmartphoneStudyProtocol.local({String? name, List<
Measure> ? measures}) -
Creates a SmartphoneStudyProtocol for local data collection
using this smartphone as the primary device and with just one
participant role called "Participant".
factory
Properties
-
applicationData
↔ Map<
String, dynamic> ? -
The SmartphoneApplicationData as JSON.
getter/setter pairinherited
- applicationName → String?
-
The name of the application which will execute this protocol.
no setterinherited
-
assignedDevices
↔ Map<
String, Set< ?String> > -
Per device role, the participant roles to which the device is assigned.
Unassigned device are assigned to "anyone".
getter/setter pairinherited
-
connectedDevices
↔ Set<
DeviceConfiguration< ?DeviceRegistration> > -
The devices this device needs to connect to.
getter/setter pairinherited
-
connections
↔ List<
DeviceConnection> ? -
The connections between
primaryDevicesandconnectedDevices.getter/setter pairinherited - createdOn ↔ DateTime
-
When the object represented by this snapshot was created, in UTC.
getter/setter pairinherited
- dataEndPoint ↔ DataEndPoint?
-
Where and how to store or upload the data collected in this study.
getter/setter pairinherited
- description ↔ String
-
The description from studyDescription, or an empty string if none.
getter/setter pairinherited-getteroverride-setter
-
devices
→ Set<
DeviceConfiguration< DeviceRegistration> > -
The full list of devices part of this configuration.
no setterinherited
-
expectedParticipantData
↔ Set<
ExpectedParticipantData> ? -
getter/setter pairinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
- id ↔ String
-
Unique id for this object. A random UUID (v4) if not specified.
getter/setter pairinherited
- name ↔ String
-
A unique descriptive name for the protocol assigned by the protocol owner.
getter/setter pairinherited
- ownerId ↔ String
-
The entity (e.g., person or group) that created this study protocol.
getter/setter pairinherited
-
participantRoles
↔ Set<
ParticipantRole> ? -
Roles which can be assigned to participants in the study and
ParticipantAttributes can be linked to. If aParticipantAttributeis not linked to any specific participant role, the participant data can be filled out by all participants in the study deployment.getter/setter pairinherited -
primaryDevice
→ PrimaryDeviceConfiguration<
DeviceRegistration> -
The first of all the
primaryDevices.no setterinherited -
primaryDevices
↔ Set<
PrimaryDeviceConfiguration< DeviceRegistration> > -
The set of devices which are responsible for aggregating and synchronizing
incoming data.
getter/setter pairinherited
- privacySchemaName ↔ String?
-
The name of a PrivacySchema to be used for protecting sensitive data.
getter/setter pairinherited
- protocolApiLevel → String?
-
The API level used by this study protocol.
no setterinherited
- protocolVersionTag → String?
-
The version tag of the study protocol snapshot.
no setterinherited
- responsible → StudyResponsible?
-
The PI responsible for this protocol, taken from studyDescription.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- studyDescription ↔ StudyDescription?
-
The description of this study protocol containing the title, description,
purpose, and the responsible researcher for this study.
getter/setter pairinherited
-
taskControls
↔ Set<
TaskControl> -
Stores which tasks need to be started or stopped when the conditions
defined by
triggersare met.getter/setter pairinherited -
tasks
↔ Set<
TaskConfiguration> -
The tasks which measure data and/or present output on a device.
getter/setter pairinherited
-
triggers
↔ Map<
String, TriggerConfiguration> -
The list of triggers with assigned IDs which can start or stop tasks in
this study protocol.
getter/setter pairinherited
- version ↔ int
-
The number of edits made to the object represented by this snapshot,
indicating its version number. Starts at 0.
getter/setter pairinherited
Methods
-
addApplicationData(
String key, dynamic value) → void -
Adds app-specific
valueunderkey.inherited -
addConnectedDevice(
DeviceConfiguration< DeviceRegistration> device, PrimaryDeviceConfiguration<DeviceRegistration> primaryDevice) → bool -
Adds
deviceas connected toprimaryDevice, plus aMonitoringTaskfor it.override -
addExpectedParticipantData(
ExpectedParticipantData expectedData) → bool -
Add expected participant data to be input by users.
inherited
-
addParticipantRole(
ParticipantRole role) → bool -
Add a participant role which can be assigned to participants in the study.
inherited
-
addPrimaryDevice(
PrimaryDeviceConfiguration< DeviceRegistration> primaryDevice) → bool -
Adds
primaryDeviceand aMonitoringTaskfor it.override -
addTask(
TaskConfiguration task) → void -
Add the
taskto this protocol.inherited -
addTaskControl(
TriggerConfiguration trigger, TaskConfiguration task, [DeviceConfiguration< DeviceRegistration> ? destinationDevice, Control control = Control.Start]) → bool -
Add a
taskto be started (default) or stopped (determined bycontrol) on adestinationDeviceonce atriggerwithin this protocol is initiated. In case thetriggerortaskare not yet included in this study protocol, it will be added. ThedestinationDeviceneeds to be added prior to this call since it needs to be set up as either a primary device or connected device. IfdestinationDeviceis not specified, the default primary device (i.e.,primaryDevice) is used.inherited -
addTaskControls(
TriggerConfiguration trigger, List< TaskConfiguration> tasks, DeviceConfiguration<DeviceRegistration> destinationDevice, [Control control = Control.Start]) → void -
Add a list of
tasksto be started or stopped (determined bycontrol) on adestinationDeviceonce atriggerwithin this protocol is initiated. In case thetriggerortasksare not yet included in this study protocol, it will be added. ThedestinationDeviceneeds to be added prior to this call since it needs to be set up as either a primary device or connected device.inherited -
addTrigger(
TriggerConfiguration trigger) → void -
Add the
triggerto this protocol, if not already added.inherited -
changeDeviceAssignment(
PrimaryDeviceConfiguration< DeviceRegistration> device, AssignedTo assignedTo) → void -
Change who the primary
deviceisassignedTo.inherited -
getApplicationData(
String key) → dynamic -
The app-specific value stored under
key, ornullif none.inherited -
getConnectedDevices(
PrimaryDeviceConfiguration< DeviceRegistration> primaryDevice) → List<DeviceConfiguration< DeviceRegistration> > -
Gets all devices configured to be connected to
primaryDevice.inherited -
getDeviceByRoleName(
String roleName) → DeviceConfiguration< DeviceRegistration> ? -
The primary or connected device with
roleName, ornullif not found. -
getTaskControls(
TriggerConfiguration trigger) → Set< TaskControl> -
Gets all conditions which control that tasks get started or stopped on
devices in this protocol by the specified
trigger.inherited -
getTaskControlsByTriggerId(
int triggerId) → Set< TaskControl> -
Gets all conditions which control that tasks get started or stopped on devices
in this protocol by the trigger with
triggerId.inherited -
getTasksForDevice(
DeviceConfiguration< DeviceRegistration> device) → Set<TaskConfiguration?> -
Gets all the tasks triggered for the specified
device. Ifdeviceis not part of eitherprimaryDevicesorconnectedDevices, an empty set is returned.inherited -
getTasksForDeviceRoleName(
String deviceRoleName) → Set< TaskConfiguration> -
Gets all the tasks triggered for the specified
deviceRoleName.inherited -
hasPrimaryDevice(
String roleName) → bool -
Does this protocol have a primary device with role name
roleName?inherited -
indexOfTrigger(
TriggerConfiguration trigger) → int -
Returns the index of the
triggerin thetriggers. Returns-1if not found.inherited -
isValidAssignment(
AssignedTo assignment) → bool -
Determines whether all participant roles in
assignmentare part of theparticipantRolesin this protocol.inherited -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
removeApplicationData(
String key) → void -
inherited
-
removeDeviceAssignment(
PrimaryDeviceConfiguration< DeviceRegistration> device) → void -
Remove the primary
deviceassignments and hence make it assigned to all roles.inherited -
removeExpectedParticipantData(
ExpectedParticipantData expectedData) → bool -
Remove expected participant data to be input by users.
inherited
-
removeTask(
TaskConfiguration task) → void -
Remove the
taskcurrently present in this configuration including removing it from anyTaskControl's which initiate it.inherited -
toJson(
) → Map< String, dynamic> -
override
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Constants
- CAMS_DEMO_APP_NAME → const String
- The applicationName of the CARP Mobile Sensing demo app.
- CAMS_EXAMPLE_APP_NAME → const String
- The applicationName of the example app included in CAMS.
- CAMS_PROTOCOL_API_LEVEL → const String
- The API level used by study protocols. This reflects the major version of the CARP Mobile Sensing framework as set in the pubspec.yaml file.
- CARP_STUDY_APP_NAME → const String
- The applicationName of the CARP Studies app.
- PULMONARY_MONITOR_APP_NAME → const String
- The applicationName of the Pulmonary Monitor demo app.