Sleep Macros

Use value macro expressions for sleep analysis in Junction Sense queries to access computed sleep stage metrics and breakdowns.

Macros are precomputed fields available in the Junction Sense DSL. Use them anywhere you would use a regular column expression. Reference a macro with the value_macro expression:

JSON DSL

{
    "select": [
        { "value_macro": "chronotype" }
    ]
}

import vitalx.aggregation as va

va.select(va.Sleep.chronotype())

Available Sleep Macros

Macro Name	Description	Output Column Name
Chronotype	The chronotype of the sleep session, categorized as lark, third, or owl.	chronotype
Sleep Score	A score from 0 to 100 computed using the Junction Sense Sleep Score model.	sleep_score
Asleep At	Computed time of user falling asleep based on sleep session start time and latency.	asleep_at
Awake At	Computed time the user woke up (may differ from session end time).	awake_at
Awakenings	Count of transitions from a sleeping phase to an awake phase, computed from sleep cycle hypnogram data.	awakenings

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" } },
        { "func": "mean", "arg": { "value_macro": "awakenings" } }
    ],
    "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

Python DSL

import vitalx.aggregation as va

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

{
    "select": [
        { "func": "latest", "arg": { "value_macro": "chronotype" } }
    ],
    "group_by": [
        {
            "date_trunc": {
                "unit": "week",
                "value": 1
            },
            "arg": {
                "index": "sleep"
            }
        }
    ]
}

Sleep Score

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

Get mean sleep score of the week

Python DSL

import vitalx.aggregation as va

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

{
    "select": [
        { "func": "mean", "arg": { "value_macro": "sleep_score" } }
    ],
    "group_by": [
        {
            "date_trunc": {
                "unit": "week",
                "value": 1
            },
            "arg": {
                "index": "sleep"
            }
        }
    ]
}

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

Python DSL

import vitalx.aggregation as va

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

{
    "select": [
        { "func": "mean", "arg": { "value_macro": "asleep_at" } },
        { "func": "mean", "arg": { "value_macro": "awake_at" } }
    ],
    "group_by": [
        {
            "date_trunc": {
                "unit": "week",
                "value": 1
            },
            "arg": {
                "index": "sleep"
            }
        }
    ]
}

Awakenings

Count the number of times a user transitioned from a sleeping phase (deep, light, or REM) to an awake phase during a sleep session. This is computed from sleep cycle hypnogram data.

Get average nightly awakenings per week

Python DSL

import vitalx.aggregation as va

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

{
    "select": [
        { "func": "mean", "arg": { "value_macro": "awakenings" } }
    ],
    "group_by": [
        {
            "date_trunc": {
                "unit": "week",
                "value": 1
            },
            "arg": {
                "index": "sleep"
            }
        }
    ]
}