API Concepts - Health123/wiki GitHub Wiki
Signals
All data recorded as an event or measurement is stored and retrieved as a signal value object. Signals can be thought of as a message stream, and will often have listeners and/or post-write hooks or callbacks. In turn, these listeners may also write their output back to the signal stream. Signals may also be treated as time series data and retrieved in slices.
Signals are the base atomic representation of metric values within the system. Besides biometric values, all other metrics are also written as signals. This includes usage and behavioral metrics, computational results, and various status values.
Every participant action known to the system is recorded as a signal value of some type. Besides biometrics and other signals of direct interest, this also includes indirect signals such as sign up and log in events, completion of tasks, or participation in coaching.
Compound values, e.g. systolic and diastolic blood pressure, are recorded as a tuple: independent signal values with the same tuple ID.
Tuples vs. Signal Groups: While these both express a relationship between signal values, they have very different meaning and semantics. Signal groups operate on signal types, and allow grouping of related types for presentation purposes. They are effectively views, and signal types may be part of many signal groups, or even added or removed from groups dynamically. Tuples work at the signal value layer to provide strong binding between specific values that were recorded at the same time and as part of the same tightly bound set. It is not expected that members of such a set are dynamic, or should belong to two sets.
A signal group is correctly used to display systolic and diastolic blood pressure together. Tuples are used to ensure the two values rendered were actually the two values that were recorded together. Tuples may also be used to ensure calculated values (e.g. min, max, mean, etc.) over the same range are bound together.
Sources: The source of a recorded signal value is not the initiator in an audit or security sense. It is the initiator in the sense of object relationships within the system. Therefore, if a value is written via API on behalf of a coach, the source associated with the value is the coach. The API requestor is logged separately, and this information is not currently returned via the API.
Disposition: For a given signal type, the set of disposition metadata describes all valid ranges of values for the type, as well as the relative favorability of values within each range. The expectation is that the author of the signal type definition may define both an allowable range of values, as well as the favorability expressed as a score between 0 and 100 inclusive. If the set is empty, it is ignored.
Steps
Steps and step groups describe collections of actions the participant is expected to perform, and their current status. These actions and their status are tracked via goal templates.