> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junction.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```jsonc JSON DSL theme={null}
  {
      "select": [
          { "value_macro": "chronotype" }
      ]
  }
  ```

  ```python Python DSL theme={null}
  import vitalx.aggregation as va

  va.select(va.Sleep.chronotype())
  ```
</CodeGroup>

### Available Sleep Macros

| <span style={{ whiteSpace: "nowrap" }}>Macro Name</span> | Description                                                                                             | <span style={{ whiteSpace: "nowrap" }}>Output Column Name</span> |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **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

```json theme={null}
{
    "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

<CodeGroup>
  ```python Python DSL theme={null}
  import vitalx.aggregation as va

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

  ```jsonc JSON DSL theme={null}
  {
      "select": [
          { "func": "latest", "arg": { "value_macro": "chronotype" } }
      ],
      "group_by": [
          {
              "date_trunc": {
                  "unit": "week",
                  "value": 1
              },
              "arg": {
                  "index": "sleep"
              }
          }
      ]
  }
  ```
</CodeGroup>

## Sleep Score

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

### Get mean sleep score of the week

<CodeGroup>
  ```python Python DSL theme={null}
  import vitalx.aggregation as va

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

  ```jsonc JSON DSL theme={null}
  {
      "select": [
          { "func": "mean", "arg": { "value_macro": "sleep_score" } }
      ],
      "group_by": [
          {
              "date_trunc": {
                  "unit": "week",
                  "value": 1
              },
              "arg": {
                  "index": "sleep"
              }
          }
      ]
  }
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python Python DSL theme={null}
  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")
  )
  ```

  ```jsonc JSON DSL theme={null}
  {
      "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"
              }
          }
      ]
  }
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python Python DSL theme={null}
  import vitalx.aggregation as va

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

  ```jsonc JSON DSL theme={null}
  {
      "select": [
          { "func": "mean", "arg": { "value_macro": "awakenings" } }
      ],
      "group_by": [
          {
              "date_trunc": {
                  "unit": "week",
                  "value": 1
              },
              "arg": {
                  "index": "sleep"
              }
          }
      ]
  }
  ```
</CodeGroup>