Skip to main content
Macros are precomputed fields available in the Vital Aggregation DSL. Use them anywhere you would use a regular column expression. Reference a macro with the value_macro expression: 
{
    "select": [
        { "value_macro": "chronotype" }
    ]
}

​
Available Sleep Macros

Macro NameDescriptionOutput Column Name
ChronotypeThe chronotype of the sleep session, categorized as lark, third, or owl.chronotype
Sleep ScoreA score from 0 to 100 computed using the Vital Horizon AI Sleep Score model.sleep_score
Asleep AtComputed time of user falling asleep based on sleep session start time and latency.asleep_at
Awake AtComputed time the user woke up (may differ from session end time).awake_at
You can combine multiple sleep macros in a single query and mix them with standard aggregations or other select expressions.

​
Example query

{
    "select": [
        { "group_key": "*" },
        { "func": "mean", "arg": { "value_macro": "sleep_score" } },
        { "func": "mean", "arg": { "sleep": "efficiency" } },
        { "func": "newest", "arg": { "value_macro": "chronotype" } },
        { "func": "newest", "arg": { "value_macro": "asleep_at" } },
        { "func": "newest", "arg": { "value_macro": "awake_at" } }
    ],
    "group_by": [
        {
            "date_trunc": { "value": 1, "unit": "week" },
            "arg": { "index": "sleep" }
        }
    ]
}

​
Chronotype

Determine the chronotype of each sleep session. Chronotype categories are based on the sleep midpoint time:
  • lark if midpoint ≥ 17:00 or ≤ 03:30
  • third if midpoint ≤ 06:00
  • owl otherwise

​
Get last chronotype of the week

import vitalx.aggregation as va

va.select(
    va.Sleep.chronotype().latest()
).group_by(
    date_trunc(Sleep.index(), 1, "week")
)

​
Sleep Score

Calculate a Sleep Score (0 to 100) for each sleep session.

​
Get mean sleep score of the week

import vitalx.aggregation as va

va.select(
    va.Sleep.score().mean()
).group_by(
    date_trunc(Sleep.index(), 1, "week")
)

​
Awake At / Asleep At

Pinpoint when a user first fell asleep and when they became fully awake during each sleep session. The asleep_at macro returns the bedtime start adjusted by the recorded sleep latency, while awake_at returns the bedtime start plus the offset of the final non-awake sleep segment.

​
Get mean asleep at and awake at of the week

import vitalx.aggregation as va

va.select(
    va.Sleep.asleep_at().mean(),
    va.Sleep.awake_at().mean()
).group_by(
    date_trunc(Sleep.index(), 1, "week")
)