carp_core library

This library contains the core domain model for the Copenhagen Research Platform (CARP). This is a Dart implementation of the Kotlin CARP Core Domain Model. This is used in the CARP Mobile Sensing (CAMS) framework implemented in Flutter, and all of its sub-packages.

Following CARP Core, this package consists of five sub-systems:

protocol - supports the creation and management of StudyProtocols defining how a study should run. Essentially, this subsystem has no technical dependencies on any particular sensor technology or application as the containing study protocols merely describe why, when, and what data should be collected.
deployment - maps the information specified in a study protocol to runtime configurations called StudyDeployments, which is used by the client subsystems to run the protocol on concrete devices (e.g., a SmartphoneClient) and allow researchers to monitor their state. To start collecting data, participants need to be invited, the deployment information has to be fetched, and devices need to be registered to collect the measures specified in the study protocol.
client - the runtime which performs the actual data collection on a device (e.g., a smartphone). This subsystem contains reusable components which understand the runtime configuration derived from a study protocol by the deployment subsystem. Integrations with sensors are loaded through a DeviceDataCollector plug-in system to decouple sensing from the abstract deployment information. For example, a study deployment may specify that Geolocation should be collected, while a different data collectors on different devices may collect this information using different OS-specific sensors or APIs.
data - handles all data collected by a client. Data is collected as Measurements which again holds Data objects. Data collection happens pseudonymized as each measurement does not contain any information about the participant collecting this data. However, in combination with the original study protocol, the full provenance of the data (when/why it was collected) is known.
common - implements base types and helper classes used by all subsystems. Primarily, this contains the built-in types used to define study protocols which subsequently get passed to the deployments and clients subsystem.

Using carp_serializable, this package also handles JSON serialization of all objects between the Kotlin and Dart implementation. In order to ensure initialization of json serialization, call:

Core.ensureInitialized();

Classes

Acceleration: Change in velocity, including gravity, along perpendicular x, y, and z axes in meters per second squared (m/s^2). Typically captured by an accelerometer.
Account: Uniquely identifies an account and its associated identity.
AccountIdentity: Identifies an Account.
ActiveParticipationInvitation: An invitation to participate in an active study deployment using the assignedDevices. Some of the devices which the participant is invited to might already be registered. If the participant wants to use a different device, they will need to unregister the existing device first.
Add: An RPC request for ProtocolService.add.
AddressInput: The full address of a participant.
AddVersion: An RPC request for ProtocolService.addVersion.
AltBeacon: A beacon meeting the open AltBeacon standard.
AltBeaconDeviceRegistration: A DeviceRegistration for AltBeacon specifying which beacon to listen to.
AppendToDataStreams: An RPC request for DataStreamService.appendToDataStreams.
AssignedPrimaryDevice: Primary device and its current registration assigned to participants as part of a participant group.
AssignedTo: Determines which participant roles to assign to something.
BackgroundTask: A task which specifies that all containing measures and/or outputs should immediately start running in the background once triggered. The task runs for the specified duration, or until stopped, or until all measures and/or outputs have completed.
BatteryAwareSamplingConfiguration: A sampling configuration which changes based on how much battery the device has left.
BLEHeartRateDevice: A Bluetooth Low Energy (BLE) device which implements a GATT Heart Rate service (https://www.bluetooth.com/specifications/gatt/services/).
CarpDataTypes: Contains CARP data type definitions, as defined in CARP Core.
ClientManager<TPrimaryDevice extends PrimaryDeviceConfiguration<TRegistration>, TRegistration extends DeviceRegistration, TStudy extends Study<PrimaryDeviceDeployment>>: Allows managing studies on a client device.
ClientRepository<TStudy extends Study<PrimaryDeviceDeployment>>: A repository which handles persisting the state of studies. Used by a ClientManager to store and retrieve information about the client device and the studies it is handling.
CloseDataStreams: An RPC request for DataStreamService.closeDataStreams.
CompletedTask: Data about an interactive user task with taskName, which has been completed.
ConnectedDeviceDataCollector<TDeviceConfiguration extends DeviceConfiguration<TRegistration>, TRegistration extends DeviceRegistration>: Collects Data for a single connected device.
Core: Base class for the carp_core library.
CreateCustomProtocol: An RPC request for ProtocolFactoryService.createCustomProtocol.
CreateStudyDeployment: A request for creating a deployment based on the protocol.
CustomInput: Custom input data as requested by a researcher.
CustomProtocolDevice: A general-purpose primary device for custom protocols. Only used when downloading custom protocols from the CARP web service.
CustomProtocolTask: A task which contains a definition of a custom protocol which differs from the CARP domain model.
Data: Holds data of a specific dataType. This is a base class and contains no data as such.
DataStreamBatch: A collection of non-overlapping, ordered, data measurements.
DataStreamId: Identifies a data stream of collected dataType data on the device with deviceRoleName in a deployed study protocol with studyDeploymentId.
DataStreamsConfiguration: Configures the set of ExpectedDataStream for a study deployment.
DataStreamService: Store and retrieve data streams for study deployments.
DataStreamServiceRequest: An abstract RPC request to a DataStreamService.
DataType: Specifies the type of a Measure.
DataTypeMetaData: Contains meta data about type.
DataTypeSamplingScheme: Specifies the sampling scheme for a data type (dataType), including possible options, defaults, and constraints.
DataTypeSamplingSchemeMap: A set of DataTypeSamplingScheme mapped to their data type as String.
DefaultDeviceConfiguration: A default device configuration just implementing the basics.
DefaultDeviceRegistration: A concrete DeviceRegistration which solely implements the base properties and nothing else.
DeploymentService: Application service which allows deploying study protocols to participants and retrieving PrimaryDeviceDeployment's for participating primary devices as defined in the protocol.
DeploymentServiceRequest: A DeploymentServiceRequest and all its sub-classes contain the data for sending a RPC request to the CARP web service.
DeviceConfiguration<TRegistration extends DeviceRegistration>: Describes any type of electronic device, such as a sensor, video camera, desktop computer, or smartphone that collects data which can be incorporated into the platform after it has been processed by a primary device (potentially itself). Optionally, a device can present output and receive user input.
DeviceConnection
DeviceDataCollector: Collects Data for a single device.
DeviceDataCollectorFactory: Provides a localDataCollector to collect data locally on the primary device and supports creating ConnectedDeviceDataCollector instances for connected devices.
DeviceDeployed: A request for reporting this deployment as successful.
DeviceDeploymentStatus: A DeviceDeploymentStatus represents the status of a device in a deployment.
DeviceRegistration: A DeviceRegistration configures a DeviceConfiguration as part of the deployment of a StudyProtocol.
DiagnosisInput: The diagnosis of a patient.
ECG: Electrocardiogram data of a single lead.
EDA: Single-channel electrodermal activity (EDA) data, represented as skin conductance. Among others, also known as galvanic skin response (GSR) or skin conductance response/level.
EducationalDegreeInput: Highest completed educational degree, mapped to the ISCED framework for cross-country comparability.
ElapsedTimeTrigger: A trigger which starts a task after elapsedTime has elapsed since the start of a study deployment, i.e. when a protocol is deployed on the phone for the first time.
EmailAccountIdentity: Identifies an account by a unique emailAddress.
End: Specify how a RecurrenceRule ends.
Error: Indicates that some error occurred during data collection. message holds any message about the error which might have been captured.
ExpectedDataStream: The expected data type for a device with a specific role name.
ExpectedParticipantData: Describes a participant attribute that pertains to all or specified participants in a study.
FullNameInput: The full name of a participant.
Geolocation: Geolocation data as latitude and longitude in decimal degrees within the World Geodetic System 1984.
GetActiveParticipationInvitations: A request for getting the deployment invitations for an account id.
GetAllForOwner: An RPC request for ProtocolService.getAllForOwner.
GetBy: An RPC request for ProtocolService.getBy.
GetDataStream: An RPC request for DataStreamService.getDataStream.
GetDeviceDeploymentFor: A request for getting the deployment for this primary device.
GetParticipantData: A request for getting the status of a study deployment.
GetParticipantDataList: A request for getting the list of participant data for this a list of studyDeploymentIds.
GetStudyDeploymentStatus: A request for getting the status of a study deployment.
GetStudyDeploymentStatusList: A request for getting the status of a list of study deployment.
GetVersionHistoryFor: An RPC request for ProtocolService.getVersionHistoryFor.
GranularitySamplingConfiguration: A SamplingConfiguration which allows specifying a desired level of granularity, corresponding to expected degrees of power consumption.
HeartRate: Heart rate data in beats per minute (bpm).
InformedConsentInput: The informed consent from a participant.
InputData: Base class for all input data types.
InputType: All supported input data types.
MACAddressDeviceRegistration: A DeviceRegistration for devices which have a MAC address.
MagneticField: Magnetic field of the device in 3D space, measured in microteslas μT for each three-dimensional axis. Typically captured by a magnetometer sensor.
ManualTrigger: A trigger initiated by a user, i.e., the user decides when to start a task.
Measure: Defines data that needs to be measured/collected passively as part of a task defined by TaskConfiguration.
Measurement: The result of a measurement of data of a given dataType at a specific point or interval in time. When sensorEndTime is set, the data pertains to an interval in time; otherwise, a point in time.
MonitoringTask: A task which is used for monitoring the execution of the data sampling collecting data on CompletedTask, TriggeredTask, and Error. This task is not supposed to be executed as such, but allows the addition of such monitoring measure to be added to a protocol.
NameSpace: Enumeration of data type namespaces.
NoOptionsSamplingConfiguration: A sampling configuration which does not provide any configuration options.
NoteInput: A general note about the participant.
OccupationInput: Occupation details of a participant (supports multiple selections).
OnboardingResearcherInput: Information about the researcher who onboarded the participant.
OpenDataStreams: An RPC request for DataStreamService.openDataStreams.
ParticipantAttribute: Describes expected data to be input by users related to one or multiple participants in a study.
ParticipantData: Expected participant data for all participants in a study deployment with studyDeploymentId.
ParticipantInvitation: The information which needs to be provided when inviting a participant to a deployment.
ParticipantRole: Describes a participant playing a role in a study, and whether this role isOptional.
ParticipantStatus: The status of a participant in a study deployment.
Participation: Uniquely identifies the participation of an account in a study deployment.
ParticipationService: Application service which allows inviting participants, retrieving participation invitations for study deployments, and managing data related to participants which is input by users.
ParticipationServiceRequest: A ParticipationServiceRequest and its sub-classes contain the data for sending a participant request to the CARP web service.
PersonalComputer: Configuration of an internet-connected personal computer with no built-in sensors.
PersonalComputerRegistration: A DeviceRegistration for a PersonalComputer specifying details of the PC.
PhoneNumberInput: The phone number of a participant.
PreferredLanguageInput: Preferred language of the participant.
PrimaryDeviceConfiguration<TRegistration extends DeviceRegistration>: A device which aggregates, synchronizes, and optionally uploads incoming data received from one or more connected devices (potentially just itself).
PrimaryDeviceDeployment: Contains the entire description and configuration for how a single primary device participates in running a study.
ProtocolFactoryService: Factory methods to create a StudyProtocol according to predefined templates.
ProtocolService: Application service which allows managing (multiple versions of) StudyProtocols.
ProtocolServiceRequest: An abstract RPC request to a ProtocolService.
ProtocolVersion: Specifies a specific version for a StudyProtocol, identified by a tag.
RecurrenceRule: Represents the iCalendar RFC 5545 standard recurrence rule to specify repeating events: https://tools.ietf.org/html/rfc5545#section-3.3.10
RegisterDevice: A request for registering this device.
RemoveDataStreams: An RPC request for DataStreamService.removeDataStreams.
RoleData: Expected participant data for all participants with a specific roleName.
Rotation: Rate of rotation of the device in 3D space. Typically captured by a gyroscope.
SamplingConfiguration: Contains configuration on how to sample a data stream of a given type.
Schedulable: An interface marking that a TriggerConfiguration can be scheduled.
ScheduledTrigger: A trigger which starts a task according to a recurring schedule starting on the date that the study starts.
SensorData: Holds data for a DataType collected by a sensor which may include additional sensorSpecificData.
ServiceRequest: An abstract base class for all RPC requests to CARP.
SetParticipantData: A request for adding data for a participant.
SexInput: The biological sex assigned at birth of a participant.
SignalStrength: The relative received signal strength of a wireless device. The unit of the received signal strength indicator (rssi) is arbitrary and determined by the chip manufacturer, but the greater the value, the stronger the signal.
Smartphone: Configuration of an internet-connected smartphone with built-in sensors.
SmartphoneClient: Allows managing studies on a smartphone.
Snapshot: An immutable snapshot of a CARP Core domain object. Used as the base class for serializable CARP domain objects.
SocialSecurityNumberInput: The social security number (SSN) of a participant.
StepCount: Step count data as number of steps taken in a corresponding time interval.
Stop: A request for permanently stopping a study deployment.
Study<TDeviceDeployment extends PrimaryDeviceDeployment>: A study deployment, identified by studyDeploymentId, which a client device participates in with the role deviceRoleName.
StudyDeployment: A single instantiation of a StudyProtocol, taking care of common concerns related to devices when 'running' a study.
StudyDeploymentProxy: Perform deployment actions for a Study on a client device.
StudyDeploymentStatus: A StudyDeploymentStatus represents the status of a deployment as returned from the CARP web service.
StudyInvitation: A description of a study, shared with participants once they are invited to a study.
StudyProtocol: A description of how a study is to be executed, defining the type(s) of primary device(s) (PrimaryDeviceConfiguration) responsible for aggregating data, the optional devices (DeviceConfiguration) connected to them, and the TaskControl's which lead to data collection on said devices.
StudyStatusEvent<TStudy extends Study<PrimaryDeviceDeployment>>: An event related to a running study.
TaskConfiguration: Describes requested measures to be collected by a device.
TaskControl: Specifies that once a condition of the trigger with triggerId applies, the task with taskName on destinationDeviceRoleName should be started or stopped (as specified by the control parameter).
TimeOfDay: A time on a day in 24-hour format. Used in a ScheduledTrigger.
TriggerConfiguration: Any condition on a device (DeviceConfiguration) which starts or stops TaskConfigurations at certain points in time when the condition applies. The condition can either be time-bound, based on data streams, initiated by a user of the platform, or a combination of these.
TriggeredTask: Indicates the task with taskName was started or stopped (control) by the trigger with triggerId on the device with destinationDeviceRoleName, referring to identifiers in the study protocol. triggerData may contain additional information related to the circumstances which caused the trigger to fire.
UnregisterDevice: A request for unregistering this device.
UpdateParticipantDataConfiguration: An RPC request for ProtocolService.updateParticipantDataConfiguration.
UsernameAccountIdentity: Identifies an account by a unique username.
WebBrowser: Configuration of an internet-connected web browser device with no built-in sensors.
WebBrowserRegistration: A DeviceRegistration for a WebBrowser specifying details of the browser.
WebTask: Redirects to a web page which contains the task which needs to be performed. The passive measures are started when the website is opened and stopped when it is closed.

Enums

Control: Determines what to do with a task once the condition of a trigger is met.
DataTimeType: Describes how Data for a DataType is stored temporally.
DeviceDeploymentStatusTypes: The types of device deployment status.
EndType: Specify how a RecurrenceRule may end as specified in End.
Frequency: Specify repeating events in a RecurrenceRule based on an interval of a chosen type or multiples thereof.
Granularity: The level of detail a data stream should be sampled at, corresponding to expected degrees of power consumption.
IscedLevel: The ISCED framework education levels.
Sex: Biological sex of a person.
StudyDeploymentStatusTypes: The types of study deployment status.
StudyStatus: Describes the status of a Study.
StudyStatusEventTypes: Different types of event that happens to a study while running.

Exceptions / Errors

IllegalArgumentException: Exception thrown when the argument provided to a method is invalid.
IllegalStateException: Exception thrown when the application is in an illegal state.
NotConfiguredException: Exception thrown when a required component has not been configured properly.

carp_core library

Classes

Enums

Exceptions / Errors

carp_core package

carp_core library