StudyProtocol

A description of how a study is to be executed.

A protocol defines the primary device(s) (PrimaryDeviceConfiguration) responsible for aggregating data, the optional devices (DeviceConfiguration) connected to them, and the TaskControls which lead to data collection on said devices. It does not depend on any sensor technology or app.

Key points:

• Add a primary device first; addTaskControl and addTrigger use primaryDevice as the default device.
• addTaskControl adds a trigger, a task and the TaskControl that links them in one call.
• Task names and device role names must be unique within a protocol.
• A protocol is deployed with DeploymentService.createStudyDeployment, which creates a StudyDeployment. CARP Mobile Sensing extends it as SmartphoneStudyProtocol.

var protocol = StudyProtocol(ownerId: 'alice@example.com', name: 'Steps');
var phone = Smartphone();
protocol.addPrimaryDevice(phone);
protocol.addTaskControl(
  phone.atStartOfStudy,
  BackgroundTask(measures: [Measure(type: CarpDataTypes.STEP_COUNT)]),
  phone,
);

Inheritance

• Object
• Snapshot
• StudyProtocol

Annotations

• @JsonSerializable(includeIfNull: false, explicitToJson: true)

Constructors

StudyProtocol.fromJson

StudyProtocol.fromJson(

1. Map<String, dynamic> json

)

StudyProtocol

StudyProtocol({

1. required String ownerId,
2. required String name,
3. String? description,

})

Create a new protocol. ownerId and name must be specified.

Constants

PROTOCOL_NAMESPACE

String const PROTOCOL_NAMESPACE

The JSON namespace of the protocol domain types.

Properties

applicationData

Map<String, dynamic>? applicationData

getter/setter pair

Application-specific data to be stored as part of the study protocol which will be included in all deployments of this study protocol.

This can be used by infrastructures or concrete applications which require exchanging additional data between the protocols and clients subsystems, outside of scope or not yet supported by CARP core.

assignedDevices

Map<String, Set<String>>? assignedDevices

getter/setter pair

Per device role, the participant roles to which the device is assigned. Unassigned device are assigned to "anyone".

connectedDevices

Set<DeviceConfiguration<DeviceRegistration>>? connectedDevices

getter/setter pair

The devices this device needs to connect to.

connections

List<DeviceConnection>? connections

getter/setter pair

The connections between primaryDevices and connectedDevices.

description

String? description

getter/setter pair

An optional description for the study protocol.

devices

Set<DeviceConfiguration<DeviceRegistration>> get devices

The full list of devices part of this configuration.

expectedParticipantData

Set<ExpectedParticipantData>? expectedParticipantData

getter/setter pair

name

String name

getter/setter pair

A unique descriptive name for the protocol assigned by the protocol owner.

ownerId

String ownerId

getter/setter pair

The entity (e.g., person or group) that created this study protocol.

participantRoles

Set<ParticipantRole>? participantRoles

getter/setter pair

Roles which can be assigned to participants in the study and ParticipantAttributes can be linked to. If a ParticipantAttribute is not linked to any specific participant role, the participant data can be filled out by all participants in the study deployment.

primaryDevice

PrimaryDeviceConfiguration<DeviceRegistration> get primaryDevice

The first of all the primaryDevices.

This is a convenient method used when there is only one primary device, which is most of the cases in Flutter where the primary device is typically the phone.

primaryDevices

Set<PrimaryDeviceConfiguration<DeviceRegistration>> primaryDevices

getter/setter pair

The set of devices which are responsible for aggregating and synchronizing incoming data.

taskControls

Set<TaskControl> taskControls

getter/setter pair

Stores which tasks need to be started or stopped when the conditions defined by triggers are met.

tasks

Set<TaskConfiguration> tasks

getter/setter pair

The tasks which measure data and/or present output on a device.

triggers

Map<String, TriggerConfiguration> triggers

getter/setter pair

The list of triggers with assigned IDs which can start or stop tasks in this study protocol.

Methods

addApplicationData

void addApplicationData(

1. String key,
2. dynamic value

)

Add any application-specific value with a key to this protocol.

addConnectedDevice

bool addConnectedDevice(

1. DeviceConfiguration<DeviceRegistration> device,
2. PrimaryDeviceConfiguration<DeviceRegistration> primaryDevice

)

Add a device which is connected to the primaryDevice. Its role name should be unique in the protocol.

Returns true if the device has been added; false if it is already connected to the specified primaryDevice.

addExpectedParticipantData

bool addExpectedParticipantData(

1. ExpectedParticipantData expectedData

)

Add expected participant data to be input by users.

Returns true if the expectedData has been added; false in case the same expectedData has already been added before.

addParticipantRole

bool addParticipantRole(

1. ParticipantRole role

)

Add a participant role which can be assigned to participants in the study.

Returns true if the role has been added; false in case the same role has already been added before.

addPrimaryDevice

bool addPrimaryDevice(

1. PrimaryDeviceConfiguration<DeviceRegistration> primaryDevice

)

Add a primary device (e.g., a phone) which is responsible for aggregating and synchronizing incoming data. Its role name should be unique in the protocol.

Returns true if the primaryDevice has been added; false if it is already set as a primary device.

addTask

void addTask(

1. TaskConfiguration task

)

Add the task to this protocol.

A task with the same name replaces the earlier one in the task lookup.

addTaskControl

bool addTaskControl(

1. TriggerConfiguration trigger,
2. TaskConfiguration task, [
3. DeviceConfiguration<DeviceRegistration>? destinationDevice,
4. Control control = Control.Start,

])

Add a task to be started (default) or stopped (determined by control) on a destinationDevice once a trigger within this protocol is initiated. In case the trigger or task are not yet included in this study protocol, it will be added. The destinationDevice needs to be added prior to this call since it needs to be set up as either a primary device or connected device. If destinationDevice is not specified, the default primary device (i.e., primaryDevice) is used.

Throws an error if the destinationDevice is not included in this study protocol. Returns true if the task control has been added; false if the same control is already present.

addTaskControls

void addTaskControls(

1. TriggerConfiguration trigger,
2. List<TaskConfiguration> tasks,
3. DeviceConfiguration<DeviceRegistration> destinationDevice, [
4. Control control = Control.Start,

])

Add a list of tasks to be started or stopped (determined by control) on a destinationDevice once a trigger within this protocol is initiated. In case the trigger or tasks are not yet included in this study protocol, it will be added. The destinationDevice needs to be added prior to this call since it needs to be set up as either a primary device or connected device.

addTrigger

void addTrigger(

1. TriggerConfiguration trigger

)

Add the trigger to this protocol, if not already added.

Its id is the number of triggers before it ('0', '1', ...). If the trigger has no source device, primaryDevice is used.

changeDeviceAssignment

void changeDeviceAssignment(

1. PrimaryDeviceConfiguration<DeviceRegistration> device,
2. AssignedTo assignedTo

)

Change who the primary device is assignedTo.

By default, primary devices are all roles so using this method is only needed if you want to change this default assignment.

Requires that device is part of this protocol and assignedTo contains participant roles which are part of this protocol.

getApplicationData

dynamic getApplicationData(

1. String key

)

Get any application-specific data with a key.

getConnectedDevices

List<DeviceConfiguration<DeviceRegistration>> getConnectedDevices(

1. PrimaryDeviceConfiguration<DeviceRegistration> primaryDevice

)

Gets all devices configured to be connected to primaryDevice.

getTaskControls

Set<TaskControl> getTaskControls(

1. TriggerConfiguration trigger

)

Gets all conditions which control that tasks get started or stopped on devices in this protocol by the specified trigger.

Throws an error if trigger is not part of this study protocol.

getTaskControlsByTriggerId

Set<TaskControl> getTaskControlsByTriggerId(

1. int triggerId

)

Gets all conditions which control that tasks get started or stopped on devices in this protocol by the trigger with triggerId.

Throws an error if a trigger with triggerId is not defined in this study protocol.

getTasksForDevice

Set<TaskConfiguration?> getTasksForDevice(

1. DeviceConfiguration<DeviceRegistration> device

)

Gets all the tasks triggered for the specified device. If device is not part of either primaryDevices or connectedDevices, an empty set is returned.

getTasksForDeviceRoleName

Set<TaskConfiguration> getTasksForDeviceRoleName(

1. String deviceRoleName

)

Gets all the tasks triggered for the specified deviceRoleName.

Returns an empty set if the device is not part of primaryDevices or connectedDevices.

hasPrimaryDevice

bool hasPrimaryDevice(

1. String roleName

)

Does this protocol have a primary device with role name roleName?

indexOfTrigger

int indexOfTrigger(

1. TriggerConfiguration trigger

)

Returns the index of the trigger in the triggers. Returns -1 if not found.

isValidAssignment

bool isValidAssignment(

1. AssignedTo assignment

)

Determines whether all participant roles in assignment are part of the participantRoles in this protocol.

removeApplicationData

dynamic removeApplicationData(

1. String key

)

Remove any application-specific data with a key.

removeDeviceAssignment

void removeDeviceAssignment(

1. PrimaryDeviceConfiguration<DeviceRegistration> device

)

Remove the primary device assignments and hence make it assigned to all roles.

Requires that device is part of this protocol.

removeExpectedParticipantData

bool removeExpectedParticipantData(

1. ExpectedParticipantData expectedData

)

Remove expected participant data to be input by users.

Returns true if the expectedData has been removed; false if it is not included in this configuration.

removeTask

void removeTask(

1. TaskConfiguration task

)

Remove the task currently present in this configuration including removing it from any TaskControl's which initiate it.

toJson

Map<String, dynamic> toJson()

toString

1. @override

String toString()

override

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.