arcascope/arcasleep-bidoze-adult · 0.2.0

Sleep stages from triaxial accelerometer recordings.
4-class sleep stage prediction, metric reports, and hypnograms. Built with a focus on sleep-wake.

Quickstart

pip install 'arcasleep[bidoze,inference,hub]'
hf download arcascope/arcasleep-bidoze-adult --local-dir arcasleep-bidoze-adult

# One CSV per recording: epoch, start_s, wake, light, deep, rem, stage, stage_raw, is_nap, is_sib, is_spt, is_gap
# plus <name>_summary.csv: subject_id, tst_minutes, missing_data_minutes, nap_minutes
# --hypnogram also saves <name>.png (needs the [report] extra)
arcasleep bidoze predict arcasleep-bidoze-adult recordings/*.csv -o predictions/ --hypnogram

# Or draw hypnograms later from the CSVs
arcasleep hypnogram predictions/*.csv

Or from Python:

from arcasleep.predict import Predictor, read_accelerometer

predictor = Predictor("arcasleep-bidoze-adult")  # load once, reuse
accel = read_accelerometer("night.csv")  # (N, 4): t [s], x, y, z [g]
result = predictor.predict(accel)

result.probabilities   # (epochs, 4): wake, light, deep, rem
result.labels          # corrected stage per 30-s epoch, "gap" where no data
result.raw_labels      # the model's raw stage, before filtering
result.summary         # subject_id, tst_minutes, missing_data_minutes, nap_minutes
result.epoch_start_s   # epoch start times, on the input clock
result.to_csv("night_stages.csv")
result.plot("night_stages.png")     # hypnogram; needs the [report] extra

By default the corrected stage applies a GGIR-style sleep filter; the definition depends on recording length:

• ≤ 9 hours, such as a single night: nothing; stage is the model's own scoring, stage_raw.
• Longer, such as multi-day wear: GGIR estimates the main sleep period (is_spt). Inside this the model's scoring is unchanged. Outside it, sleep becomes wake unless the wrist was still for at least 5 minutes (is_sib), and the sleep that remains is flagged by is_nap == 1.

A gap of 60 minutes or more without data splits a recording, and each part is judged on its own length. Pass ggir_sleep_filter=False (or --no-ggir-sleep-filter) for the unfiltered output. The hypnogram shows the raw and filtered stages, the sleep the filter removed, and the SIB and SPT tracks.

Pass origin= (seconds on the input clock, or "unix") to put epoch boundaries somewhere other than the first sample, for example at the start of a PSG recording you want to compare with.

Performance

Metrics compare model predictions with reference PSG scoring, macro-averaged over subjects, with 95% confidence intervals of the mean.

• SleepAccel: healthy adults; cross-validation.
• SleepAccel-Clinical: adults with sleep apnea of varying severity; scored by the released model.
• Wearanize+: adults, recorded with an Empatica E4; cross-validation.

Protocol. The model is the F2 network, trained three times (three seeds) on all 634 revised-Weaver recordings (237 children) plus SleepAccel (28 recordings) and Wearanize+ (92 nights). SleepAccel and Wearanize+ were each split into five fixed, participant-level folds. The SleepAccel and Wearanize+ columns pool five fold models, each scoring the fold it did not train on, with one value per recording. The released model was trained on all of Weaver, SleepAccel and Wearanize+ and scored on SleepAccel-Clinical, which no model trained on.

All metrics, per cohort

'Higher is better' and 'lower is better' describe how to read each metric; they do not indicate improvement over a control or baseline model or a comparison between cohorts.

SleepAccel

SleepAccel-Clinical

Wearanize+

Intended use

Research estimates of sleep and wake, and of light, deep and REM sleep, from a wrist-worn accelerometer in adults. Running BiDoze does not require polysomnography (PSG). PSG can be used to measure its accuracy on your own cohort.

Sleep/wake is the primary task. Report stage estimates as cohort means, not as per-night measurements.

Not a medical device. Do not use it to diagnose sleep disorders (including obstructive sleep apnea), to screen individuals, or to make clinical decisions.

The two adult releases

There are two adult releases of BiDoze v0.2.0:

• arcasleep-bidoze-adult: three networks; their outputs are averaged.
• arcasleep-bidoze-adult-small: one network.

How they are related.

• All four networks have the same architecture (panel a) and were trained on the same recordings. Only the random seed differs.
• The adult-small network is seed 0 of adult; the weights are identical.
• Both releases use the same stage divisor and label epochs the same way. In adult, the network output used for labeling is the average of the three networks' outputs.

How their scores compare. Each value is the mean over nights, adult vs adult-small. Differences marked * are significant at p ≤ 0.05 (paired Wilcoxon over nights); unmarked differences are not.

TST error is model − PSG. Neither release was trained on SleepAccel-Clinical, AAUWSS or EESM19.

• AAUWSS: 13 healthy adults aged 22–71, one lab night each, Empatica E4.

• EESM19 (OpenNeuro ds005185): 33 nights from 16 adults, GENEActiv wrist accelerometer at 100 Hz.

• Wake specificity is higher for adult: by 2.0 points on Wearanize+, 4.5 points on SleepAccel-Clinical and 6.7 points on AAUWSS (all p < 0.001).

• Total sleep time is overestimated by 17.1 minutes with adult vs 24.0 minutes with adult-small on SleepAccel-Clinical (p < 0.001), and by 6.2 vs 15.9 minutes on AAUWSS (p = 0.001).

• No metric differs significantly on SleepAccel (sleep/wake κ difference +0.015, p = 0.093) or EESM19.

• Use adult unless model size or compute is a constraint.

How it scores a recording

The bundle holds three networks of one architecture, trained with different random seeds. Their outputs are averaged, then each 30-s epoch is labeled in two steps:

1. Sleep or wake: the epoch is wake when wake is the most probable of wake, light, deep and REM in the averaged output; otherwise it is sleep.
2. Light, deep or REM, on sleep epochs only: the light, deep and REM probabilities are each divided by a fixed stage divisor, stored as stage_divisor in config.json; the largest quotient gives the stage.

The divisor corrects for two properties of the training: the loss weights rare stages up, and most training recordings are of children, who spend a larger share of sleep in deep sleep than adults (33% of PSG sleep in the pediatric training data). The adult stage proportions in the divisor are those of the adult training recordings, SleepAccel and Wearanize+ (deep sleep 19.7% of PSG sleep).

Output columns:

• wake: the averaged probability of wake.
• light, deep, rem: 1 − wake, split in proportion to the divided probabilities.
• stage: the label from steps 1 and 2. This is not always the largest of the four columns.

Limitations

• Wake specificity is lower than sleep sensitivity.
  • SleepAccel cross-validation: sleep sensitivity 95.8%, wake specificity 74.8%.
  • Wearanize+ cross-validation: sleep sensitivity 94.5%, wake specificity 82.8%.
  • SleepAccel-Clinical: sleep sensitivity 94.5%, wake specificity 67.0%. Total sleep time is overestimated by 17.1 minutes on average.
• Stage durations have larger errors than total sleep time. On SleepAccel (cross-validation), the mean absolute percentage error is 3.8% for total sleep time, 17.9% for light sleep, 78.5% for deep sleep and 50.5% for REM sleep.
• Deep sleep is overestimated in cohorts with little deep sleep.
  • Deep sleep is 25.5% of predicted sleep vs 11.0% of PSG sleep on SleepAccel-Clinical, and 22.7% vs 16.2% on SleepAccel (cross-validation), as the mean over nights.
  • The divisor assumes the adult training recordings' 19.7% deep sleep. Cohorts with less deep sleep, such as older adults or people with sleep apnea, are overestimated more.
  • Do not use deep-sleep time as a per-night outcome.
• Single nights differ more than cohort means. 95% limits of agreement for total sleep time are −64 to +99 minutes on SleepAccel-Clinical.
• Only the PSG night has been evaluated. Daytime sleep, naps and non-wear periods in multi-day recordings have not been compared against a reference.
• Device and placement. The model was trained on wrist data from ActiGraph, Apple Watch, Empatica E4, Fitbit and Garmin devices, sampled at 12 Hz or faster. Adult recordings in training and evaluation are from Apple Watch (SleepAccel, SleepAccel-Clinical) and Empatica E4 (Wearanize+).

Training data

• Weaver et al (PubMed 40676371): 634 recordings from 237 children with no, mild, moderate and severe obstructive sleep apnea (OSA), each night recorded by up to four wrist devices (ActiGraph, Apple Watch, Fitbit and Garmin).
• SleepAccel: 28 healthy adults, Apple Watch.
• Wearanize+: 92 nights from adults, Empatica E4, with manual PSG scoring.

Not trained on:

• SleepAccel-Clinical: 32 adults with no, mild, moderate and severe OSA; evaluation only.

Input requirements

• Columns. Timestamp in seconds, then x, y, z acceleration in g (divide m/s² by 9.81), from a wrist-worn triaxial accelerometer.
• Sampling rate. At least 12 Hz; slower recordings are rejected. Irregular sampling is fine.
• Missing data. Leave gaps as gaps: never fill them with zeros or synthetic rows. Epochs with no samples come back with is_gap set; leave them out of sleep durations.
• Length. At least 2 hours recommended. Up to 25 hours are scored in one pass; longer recordings are scored in consecutive passes.

Outputs

Per 30-second epoch, one probability per stage, in this order:

is_gap is not a model output: it marks epochs with no accelerometer samples.

Model

3 narrow bi-causal networks (strands) each score every epoch: a convolution bank (kernels 3, 7, 31, 63 epochs, width 112), a bi-causal transformer (4 layers per direction) and a learned gate. A fusion transformer (2 layers, width 128, 4 heads) reads the strands' features across the whole recording and gives the per-epoch output (2.20 M parameters).

The release is 3 models of this architecture, each trained with a different seed (6,590,376 weights in all). Their weights are in model.safetensors under the prefixes member0/ to member2/. The mean of their outputs decides wake or sleep. On the epochs called sleep, the light, deep and REM probabilities are each divided by the stage divisor in config.json (deep 0.00422, light 0.00162, rem 0.00359) before the most probable stage is chosen.

log_psd spectrograms of the mag and jerk channels over 10-s windows every 2 s (60 bins, 0.1–6.0 Hz), averaged to 30-s epochs, plus one row giving the fraction of each epoch with no data. The model input for one pass is (3000, 61, 2). arcasleep.predict builds it from preprocessing.json.

Files and provenance

Check a download with sha256sum -c checksums.sha256.

_{Generated by python -m arcasleep_bidoze.release card from d47a710.}