NeuroSkill sleep and umap Commands

---

sleep — Sleep Stage Classification

Classify EEG epochs into sleep stages (Wake / N1 / N2 / N3 / REM) using relative band-power ratios and simplified AASM heuristics.

Auto-range: all sessions from the last 24 hours. By index: sleep 0 = most recent session, sleep 1 = previous, etc.

npx neuroskill sleep                          # auto: last 24h of sessions
npx neuroskill sleep 0                        # most recent session's sleep data
npx neuroskill sleep 1                        # previous session
npx neuroskill sleep --start 1740380100 --end 1740415510
npx neuroskill sleep --json | jq '.summary'
npx neuroskill sleep --json | jq '.analysis'
npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'

HTTP:

curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d '{"command":"sleep","start_utc":1740380100,"end_utc":1740415510}' | jq '.summary'

JSON Response

{
  "command": "sleep",
  "ok": true,
  "summary": {
    "total_epochs": 1054,
    "wake_epochs": 134,
    "n1_epochs": 89,
    "n2_epochs": 421,
    "n3_epochs": 298,
    "rem_epochs": 112,
    "epoch_secs": 5
  },
  "analysis": {
    "efficiency_pct": 85.2,
    "onset_latency_min": 12.5,
    "rem_latency_min": 62.0,
    "transitions": 38,
    "awakenings": 11,
    "stage_minutes": { "wake": 11, "n1": 7, "n2": 35, "n3": 25, "rem": 9 },
    "bouts": {
      "WAKE": { "count": 11, "mean_min": 1.0, "max_min": 3.5 },
      "N3":   { "count": 6,  "mean_min": 4.2, "max_min": 9.0 },
      "REM":  { "count": 4,  "mean_min": 2.3, "max_min": 4.5 }
    }
  },
  "epochs": [
    { "utc": 1740380100, "stage": 0, "rel_delta": 0.18, "rel_theta": 0.21, "rel_alpha": 0.38, "rel_beta": 0.17 }
    // ... one entry per 5-second epoch
  ]
}

Stage codes: 0 = Wake, 1 = N1, 2 = N2, 3 = N3, 4 = REM.

Hidden Fields (visible only with --full or --json)

Hidden field	Contents
epochs[]	Per-epoch classification for every 5-second window — can be thousands of entries

npx neuroskill sleep --json | jq '.epochs | length'
npx neuroskill sleep --json | jq '.epochs[0]'
npx neuroskill sleep --json | jq '[.epochs[] | select(.stage == 3)] | length'  # N3 epoch count
npx neuroskill sleep --json | jq '[.epochs[] | {utc: .utc, stage: .stage}]'    # hypnogram data

Good Sleep Targets (healthy adult, ~8h)

• N3 (slow-wave): 15–25% of total sleep
• REM: 20–25%
• Sleep efficiency: > 85%
• Sleep onset: < 20 min

---

umap — 3D UMAP Projection

Compute a 3D UMAP projection of EEG embedding vectors from two sessions. Runs GPU-accelerated UMAP; the CLI polls for progress and prints a live bar. Results are cached so re-running the same ranges is instant.

Auto-range: last two sessions (same as compare).

npx neuroskill umap                           # auto: last 2 sessions
npx neuroskill umap --a-start 1740380100 --a-end 1740382665 \
                 --b-start 1740412800 --b-end 1740415510
npx neuroskill umap --json | jq '.result.points | length'
npx neuroskill umap --json | jq '.result.points[0]'
npx neuroskill umap --json | jq '[.result.points[] | select(.session == "A")] | length'
npx neuroskill umap --json | jq '.result.analysis.separation_score'

HTTP (two requests — enqueue then poll):

# Step 1 — enqueue:
JOB=$(curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d '{"command":"umap","a_start_utc":1740380100,"a_end_utc":1740382665,"b_start_utc":1740412800,"b_end_utc":1740415510}')
JOB_ID=$(echo $JOB | jq '.job_id')

# Step 2 — poll until complete:
until [ "$(curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d "{\"command\":\"umap_poll\",\"job_id\":$JOB_ID}" | jq -r '.status')" = "complete" ]; do
  sleep 2
done

JSON Response

{
  "status": "complete",
  "elapsed_ms": 8432,
  "result": {
    "points": [
      { "x": 1.23, "y": -0.45, "z": 2.01, "session": "A", "utc": 1740380105, "label": null },
      { "x": 1.31, "y": -0.38, "z": 1.94, "session": "A", "utc": 1740380110, "label": "eyes closed" },
      { "x": -0.87, "y": 1.34, "z": -1.22, "session": "B", "utc": 1740412805 }
    ],
    "n_a": 513, "n_b": 541, "dim": 3,
    "analysis": {
      "separation_score": 1.84,      // higher = better A/B separation
      "inter_cluster_distance": 2.31,
      "intra_spread_a": 0.82,
      "intra_spread_b": 0.94,
      "centroid_a": [1.23, -0.45, 2.01],
      "centroid_b": [-0.87, 1.34, -1.22],
      "n_outliers_a": 3,
      "n_outliers_b": 5
    }
  }
}

Hidden Fields

Hidden field	Contents
result.points[]	3D coordinates for every embedding epoch — typically 500–2000+ entries

npx neuroskill umap --json | jq '.result.points | length'
npx neuroskill umap --json | jq '[.result.points[] | select(.session == "B")]'
npx neuroskill umap --json | jq '[.result.points[] | select(.label != null)]'  # labeled points only

Interpreting separation score:

• > 1.5 — sessions are neurally distinct (different brain states)
• < 0.5 — similar brain state across both sessions