Metrics

Carium ingests, stores, summarizes, and alerts on a variety of health metrics.

A metric data point is a tuple identified by:

1. individual-id: The individual ID
2. type (like Steps)
3. time The time the metric was recorded
4. source A free-text string identifying the source of the data (like Fitbit)

Each data point additionally has one or more value fields. For primitive types, this is a single value value field. For complex fields, multiple additional fields are stored on the data point JSON object.

Once ingested, a data point is immutable. If a data point is updated, a new data point is created with the updated value and the original data point is marked as deleted.

Metric Types

Series Type	Data Type	Description
ActiveEnergyBurned	Float	Deprecated Active energy burned (kcal)
ActiveTime	Integer	Active time in minutes
AerobicSteps	Integer	Aerobic steps
AirQualityIndex	Integer	Deprecated Air quality index
Auscultation	Complex	Auscultation
BloodGlucose	Complex	Blood glucose series
BloodPressure	Complex	Blood pressure series
BodyFatPercentage	Float	Body fat percentage
BodyMass	Float	Body mass in kg
BodyMassGoal	Float	Body mass goal in kg
BodyMassIndex	Float	Body mass index
BodyMassLean	Float	Body mass lean in kg
BodyTemperature	Float	Body temperature in degrees Celsius
Covid19	Integer	Covid-19 cases
DailyActivity	Complex	Daily activity series
DailyHeartRate	Complex	Daily heart rate series
Distance	Float	Distance (meters)
Dqv	Float	Diet quality value
FeelingRating	Integer	Feeling rating
ForcedExpiratoryVolume	Float	Forced expiratory volume in Liters
FluActivity	Integer	Flu activity
HbA1c	Float	HbA1c
Height	Float	Height (meters)
Hematocrit	Float	Hematocrit series
Hemoglobin	Float	Hemoglobin series
Medication	Complex	Medication series
Mindfulness	Complex	Mindfulness series
OxygenSaturation	Float	Oxygen saturation
PeakFlow	Float	Peak flow
PeriodicPulse	Complex	Deprecated Periodic pulse
PollenGrassIndex	Integer	Deprecated Grass pollen index
PollenRagweedIndex	Integer	Deprecated Ragweed pollen index
PollenTreeIndex	Integer	Deprecated Tree pollen index
PotassiumLevel	Integer	Potassium level state
Pulse	Integer	Pulse
SleepAnalysis	Enumeration	One of IN_BED, ASLEEP, or AWAKE
Steps	Integer	Steps
SkinTemperature	Float	Skin temperature in Celsius
Vo2Max	Float	Vo2 max
WaistCircumference	Float	Waist circumference (meters)
WaterIntake	Float	Water intake in liters

Notes on Complex Metric Types

BloodGlucose takes a Float value as well as a context (one of FASTING, BEFORE_MEAL, AFTER_MEAL, BEDTIME, UNSPECIFIED).

BloodPressure takes a systolic and diastolic Integer value.

DailyActivity is primarily from Fitbit and consists of several values:

• calories (Integer)
• steps (Integer)
• distance (Float)
• floors (Integer)
• sedentary (Integer)
• active_low (Integer)
• active_medium (Integer)
• active_high (Integer)

DailyHeartRate consists of zone_max (Integer) and zone_minutes (Integer) values.

Medication consists of:

• name (String)
• value (Float)
• unit (String)
• code (UUID)

Mindfulness takes a value (Float) and a context (one of FORMAL or INFORMAL).

PotassiumLevel takes a state (one of LOW, NORMAL, HIGH).

Sources

Most metric types are pushed by devices to the POST /lachesis/v1/timeseries/ API. Some cloud-connected devices (such as Fitbit) are pulled by Carium from the device's cloud API. These metrics can be delayed by up to 24 hours, depending on the device vendor.

A smaller number of metric types are collected by Carium native Apps (for example Carium for iOS) and pushed to Carium's API. Carium manages the collection and device integration for ingestion of these metrics, which typically come from Bluetooth-connected devices.

Sending Metrics

You can push metrics to the Carium API using the POST /lachesis/v1/timeseries/ API. You should send no more than 128kb of data per request.

The attributes.type field should be one of the metrics included in body of the request. Additional metrics points can be included in the data array.

See the Submit Timeseries Data API for the full schema.

Uploading various metrics for a single individual

POST /lachesis/v1/timeseries/ HTTP/1.1
Host: api.carium.com
Content-Type: application/json
Authorization: Bearer XXX

{
  "data": [
    {
      "type": "time-series",
      "attributes": {
        "individual-id": "00000000-0000-0000-0000-000000000000",
        "type": "BodyMass",
        "data": [
            {"type": "BloodGlucose", "time": "2019-05-21 06:00:00", "value": 200, "context": "FASTING"},
            {"type": "BloodPressure", "time": "2019-05-21 06:00:00", "systolic": 150, "diastolic": 90},
            {"type": "BodyMass", "time": "2019-05-21 06:00:00", "value": 91.17},
            {"type": "OxygenSaturation", "time": "2019-05-21 06:00:00", "value": 95},
            {"type": "Pulse", "time": "2019-05-21 06:00:00", "value": 75},
        ]
      }
    }
  ]
}

Querying Metrics

Querying metrics is done through the GET /lachesis/v1/timeseries/ API, which requires supplying individual-id and type query parameters. By default, you will receive a paged response across the entire time range of the metric.

The results can be narrowed by optionally supplying begin-datetime, end-datetime.

GET /lachesis/v1/timeseries/?individual-id=00000000-0000-0000-0000-000000000000&type=BloodPressure&begin-datetime=2019-05-21 06:00:00&end-datetime=2019-05-21 07:00:00 HTTP/1.1
Host: api.carium.com
Authorization: XXX

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {"diastolic": 23, "systolic": 119, "tags": "a, b", "time": "2016-04-03 01:12:34"},
        {"time": "2016-04-05 23:47:13", "systolic": 127, "diastolic": 75},
    ],
},

Threshold Crossing Alerts

Carium can fire alerts when a metric crosses a threshold. This is useful for alerting a user or caregiver when a metric is out of range.

There are two types of threshold crossing alerts:

Watermark alerts are fired when a metric crosses a threshold. For example, a provider may want to be alerted when blood pressure is above 140/90.

Range alerts are fired when a metric is within a range for a period of time. Multiple range alerts with non-overlapping ranges are typically used together to classify a metric. For example, a provider organization may want to classify blood pressure as Stage 1 Hypertension, or Stage 2 Hypertension and take different actions based on the classification.