📘

LAMP Protocol

LAMP Protocol

The LAMP Protocol, or Application Programming Interface (API), is the formalized inter-component language used by any app or tool connecting to the LAMP Platform. It consists of major “surfaces” that describe types of data, actions that may be performed on these types of data, and access and manipulation control of these data. These “surfaces” are designed to be compatible with the Health Level 7 (HL7) organization’s Fast Healthcare Interoperability Resources (FHIR) standard resources as well as compliant with the Health Insurance Portability and Accountability Act (HIPAA).

A schema, or data blueprint, is visually and textually presented below for each type of data in relation to other types, along with a description of the properties and actions available. The use of JSON Schema at build-time codifies these schema using sets of validation rules and declared links between types and properties. Furthermore, the Spec resource types use JSON Schema at run-time to constrain data from different device sensors or activity interfaces dynamically.

image
  1. Resource
    1. Summary: an identifier-scoped packet of hierarchically-organized data.
    2. Properties
      1. id: the globally-unique identifier for this packet of data.
    3. Actions
      1. create: save a new packet of data as a Resource.
      2. read: retrieve the packet of data within the Resource.
  • update: modify the packet of data within the Resource.
  1. delete: delete an existing Resource.
  2. list: retrieve the index of all Resources for a given sub-type below.
  3. Event
    1. Summary: a timestamp-scoped packet of data, part of a time-series data stream (“event stream”).
    2. Properties
      1. timestamp: the millisecond-precision timestamp when this packet of data was recorded.
    3. Actions
      1. append: save a new packet of data as an Event.
      2. remove: delete an existing Event.
  • search: retrieve the timestamp-ordered set of Events for a given query.
  1. Researcher
    1. Summary: a container of Studies managed by an administrator.
    2. Properties
      1. name: the name of the owner of the Researcher resource.
      2. email: the email address of the owner of the Researcher resource.
  • studies: the set of Studies linked to the Researcher.
  1. Actions: see Resource.
  2. Study
    1. Summary: a container assigning sets of Activities and Sensors to a set of Participants.
    2. Properties
      1. name: the name of the Study.
      2. activities: the set of Activities linked to the Study.
  • sensors: the set of Sensors linked to the Study.
  1. participants: the set of Participants linked to the Study.
  2. Actions: see Resource.
  3. Participant
    1. Summary: a container of streams of ActivityEvents and SensorEvents managed by a user.
    2. Properties
      1. settings: a group of arbitrary clinical records, including preferred language, set by the Participant.
      2. activity_events: an event stream consisting of active data.
  • sensor_events: an event stream consisting of passive data.
  1. Actions: see Resource.
  2. ActivitySpec
    1. Summary: a specification of a type of interactive activity, such as a game, survey, or intervention tool.
    2. Properties
      1. name: the user-friendly name of the interactive activity, such as “Jewels.”
      2. executable: the bundled HTML/JS code containing the interface to be shown by the app.
  • help: additional text or media detailing use of the interface.
  1. schema: the data schema of Activity or ActivityEvent objects, in JSONSchema format.
    1. static_data: the non-temporal packet of data contained within an ActivityEvent.
    2. temporal_slices: slices of interaction contained within a single Event.
    3. settings: the collection of possible configuration options for the interface.
  2. Actions: see Resource.
  3. Activity
    1. Summary: describing the settings and schedule of an ActivitySpec available to Participants.
    2. Notes
      1. Even if a particular ActivitySpec is available, without an Activity resource, a Participant cannot interact with that activity.
      2. Multiple Activities under a single Study may be configured against the same ActivitySpec, such as “Jewels” or “Survey,” since each Activity may have different schedules or settings.
        1. In the case of “Jewels,” an Activity named “Morning Brain Stretch” could be scheduled for MTWTF at 8:00am with moderate or light difficulty; an Activity named “Monday Marathon” could be scheduled for Monday only at 6:00pm with extreme difficulty.
        2. In the case of “Survey,” an Activity named “Anxiety” would contain questions from the GAD-7 survey instrument; an Activity named “Depression” would contain questions from the PHQ-9 survey instrument.
        3. If no schedule is provided, the user will not be notified to interact with the Activity, but it will remain available for the user to willingly use; if no settings are provided, the Activity launches with default values only.
  • While the ActivitySpec should be considered “static,” an Activity is designed to dynamically change if required and manipulated by an administrator.
  1. Properties
    1. name: the user-friendly name of the activity, defaulting to the name of the ActivitySpec.
    2. spec: the ActivitySpec that constrains this Activity and its ActivityEvents.
  • active: whether this Activity is available or not for the Participants listed.
  1. schedule: the user notification schedule, in cron-compatible syntax.
  2. settings: configuration options for this particular Activity.
  3. Actions: see Resource. Below: event stream visual representation.
  4. ActivityEvent
    1. Summary: event data stream derived from a Participant interacting with an Activity.
    2. Properties
      1. activity: the Activity that produced and constrains this ActivityEvent.
      2. duration: the duration of user interaction between recording start and stop.
  • static_data: the non-temporal packet of keyed data.
  1. temporal_slices: ordered slices of interaction data.
    1. item: the item that was interacted with; for example, in a Jewels game, the corresponding alphabet, or in a survey, the question index.
    2. value: the value of the item that was interacted with; in a Survey for example, this field would be the question choice index.
    3. type: the type of interaction that for this detail; in a Jewels game for example, ‘none’ if the tapped jewel was incorrect, or ‘correct’ if it was correct.
    4. level: the level; for example, in games with multiple levels, this field might be ‘2’ or ‘4’, but this field is not applicable to surveys.
    5. duration: the difference in time from the previous slice.
  2. Actions: see Event.
  3. SensorSpec
    1. Summary: a specification of a device sensor available.
    2. Notes
      1. It is not possible to bundle dynamically executed code for hardware device sensors.
    3. Properties
      1. name: the user-friendly name of a device sensor, such as “Accelerometer.”
      2. schema: the data schema of Sensor or SensorEvent objects, in JSONSchema format.
        1. data: the packet of data contained within a SensorEvent.
        2. settings: the collection of possible configuration options for the sensor.
      3. Actions: see Resource.
    4. Sensor
      1. Summary: describing the collection frequency and parameters of a device sensor.
      2. Notes
        1. Even if a particular SensorSpec is available, without a Sensor resource, a Participant cannot record measurements from that sensor device.
        2. Multiple Sensors under a single Study may be configured against the same SensorSpec, such as “Location,” since each Sensor may have different parameters.
          1. In the case of “Location,” an Activity named “Mobility” could collect fuzzed (i.e. anonymized) measurements every second as a facet of physical mobility; an Activity named “SocialGPS” could collect raw measurements hourly as a facet of establishments visited or local weather.
  • While the ActivitySpec should be considered “static,” an Activity is designed to dynamically change if required and manipulated by an administrator.
  1. Properties
    1. name: the user-friendly name of the sensor, defaulting to the name of the SensorSpec.
    2. spec: the SensorSpec that constrains this Sensor and its SensorEvents.
  • active: whether this Sensor is available or not for the Participants listed.
  1. settings: configuration options for this particular Sensor.
  2. Actions: see Resource.
image
  1. SensorEvent
    1. Summary: event data stream derived from a Participant’s device sensors passively.
    2. Properties
      1. sensor: the Sensor that produced and constrains this SensorEvent.
      2. data: the packet of keyed data containing a measurement and associated context.
    3. Actions: see Event.
  2. Tag
    1. Summary: a piece of arbitrary data attached to a Researcher, Study, Participant, or Activity.
    2. Properties:
    3. Actions: see Resource.
  3. Automation
    1. Summary: an automatically managed applet that is run in response to event streams or data changes.
    2. Notes
      1. The reserved identifier “me” can be used as both the source and destination below.
        1. As the source, the context can be inferred, for example, from the currently authenticated Researcher or Participant.
        2. As the destination, the applet is run upon matching events or changes from only the currently authenticated Researcher or Participant.
      2. If the destination is not an identifier, but a type of Resource, such as “Participant,” changes are monitored across all resources of that type, provided those resources exist within the context of the provided source.
    3. Properties
      1. source: the owner of the Automation, preserved as the security and execution context.
      2. destination: the recipient object(s) of the Automation, upon which changes are monitored.
  • events: the Event stream or Resource change notifications that cause applet execution.
  1. executable: the applet code, dependency list, and runtime type: R, Python, JS.
  2. Actions: see Resource.
  3. Credential
    1. Summary: access control for a Researcher, Study, or Participant.
    2. Properties
      1. origin: the resource that defines the scope and ownership of this Credential.
      2. description: a user-friendly description of the credential, such as “API Key” or “Mother.”
  • access_key: either an email address or generated API key.
  1. secret_key: either a salted and hashed password or generated API secret.
  2. Actions: see Resource.

Boundaries

When requesting buckets of events (using ActivityEvent::all_by_participant() or SensorEvent::all_by_participant(), for example), you may specify a start and end boundary within which events with matching timestamps are captured. If you specify both start and end such that start == end, you'll restrict the boundary to return only a single event, and if you don't specify both, you'll un-restrict the boundary and request every event. You can also specify an origin that limits the bucket of events or subscription to its stream to a single type of activity or a single type of sensor. For Activity events (ActivityEvent), you can specify an origin that matches your configured activity or to all activities of a given type. You can request buckets of events from a stream or subscribe to the stream directly and be notified when new events appear or old ones are deleted. This follows a typical WebSocket PubSub pattern.

image

Was there something we didn't cover, or need more help? Let us know by making a post in the LAMP Community, or contact us directly. Thank you for your contribution! 🌟 Page last updated on January 29th, 2020.