arcasleep 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. arcasleep-0.1.1/.gitignore +16 -0
  2. arcasleep-0.1.1/LICENSE +21 -0
  3. arcasleep-0.1.1/MANIFEST.in +15 -0
  4. arcasleep-0.1.1/PKG-INFO +161 -0
  5. arcasleep-0.1.1/README.md +94 -0
  6. arcasleep-0.1.1/arcasleep.egg-info/PKG-INFO +161 -0
  7. arcasleep-0.1.1/arcasleep.egg-info/SOURCES.txt +78 -0
  8. arcasleep-0.1.1/arcasleep.egg-info/dependency_links.txt +1 -0
  9. arcasleep-0.1.1/arcasleep.egg-info/entry_points.txt +2 -0
  10. arcasleep-0.1.1/arcasleep.egg-info/requires.txt +57 -0
  11. arcasleep-0.1.1/arcasleep.egg-info/scm_file_list.json +109 -0
  12. arcasleep-0.1.1/arcasleep.egg-info/scm_version.json +8 -0
  13. arcasleep-0.1.1/arcasleep.egg-info/top_level.txt +3 -0
  14. arcasleep-0.1.1/bidoze/README.md +113 -0
  15. arcasleep-0.1.1/bidoze/src/arcasleep_bidoze/__init__.py +1 -0
  16. arcasleep-0.1.1/bidoze/src/arcasleep_bidoze/family.py +100 -0
  17. arcasleep-0.1.1/bidoze/src/arcasleep_bidoze/model/__init__.py +9 -0
  18. arcasleep-0.1.1/bidoze/src/arcasleep_bidoze/model/constants.py +18 -0
  19. arcasleep-0.1.1/bidoze/src/arcasleep_bidoze/model/definition.py +3591 -0
  20. arcasleep-0.1.1/bidoze/src/arcasleep_bidoze/training.py +374 -0
  21. arcasleep-0.1.1/bidoze/tests/test_balanced_recipe.py +168 -0
  22. arcasleep-0.1.1/bidoze/tests/test_curriculum_schedule.py +55 -0
  23. arcasleep-0.1.1/bidoze/tests/test_live_model.py +24 -0
  24. arcasleep-0.1.1/bidoze/tests/test_publish.py +535 -0
  25. arcasleep-0.1.1/core/src/arcasleep/__init__.py +8 -0
  26. arcasleep-0.1.1/core/src/arcasleep/artifacts/__init__.py +0 -0
  27. arcasleep-0.1.1/core/src/arcasleep/artifacts/provenance.py +196 -0
  28. arcasleep-0.1.1/core/src/arcasleep/artifacts/publish.py +1468 -0
  29. arcasleep-0.1.1/core/src/arcasleep/artifacts/templates/quickstart.md +52 -0
  30. arcasleep-0.1.1/core/src/arcasleep/artifacts/upload.py +120 -0
  31. arcasleep-0.1.1/core/src/arcasleep/cli.py +1241 -0
  32. arcasleep-0.1.1/core/src/arcasleep/data/batching.py +197 -0
  33. arcasleep-0.1.1/core/src/arcasleep/data/bundle.py +62 -0
  34. arcasleep-0.1.1/core/src/arcasleep/data/cache.py +121 -0
  35. arcasleep-0.1.1/core/src/arcasleep/data/constants.py +19 -0
  36. arcasleep-0.1.1/core/src/arcasleep/data/prepare.py +538 -0
  37. arcasleep-0.1.1/core/src/arcasleep/data/pseudonyms.py +44 -0
  38. arcasleep-0.1.1/core/src/arcasleep/data/splits.py +285 -0
  39. arcasleep-0.1.1/core/src/arcasleep/evaluation/__init__.py +12 -0
  40. arcasleep-0.1.1/core/src/arcasleep/evaluation/run.py +587 -0
  41. arcasleep-0.1.1/core/src/arcasleep/evaluation/staging_metrics.py +405 -0
  42. arcasleep-0.1.1/core/src/arcasleep/ggir.py +420 -0
  43. arcasleep-0.1.1/core/src/arcasleep/models.py +186 -0
  44. arcasleep-0.1.1/core/src/arcasleep/predict.py +611 -0
  45. arcasleep-0.1.1/core/src/arcasleep/reporting/__init__.py +5 -0
  46. arcasleep-0.1.1/core/src/arcasleep/reporting/compare.py +473 -0
  47. arcasleep-0.1.1/core/src/arcasleep/reporting/hypnogram.py +399 -0
  48. arcasleep-0.1.1/core/src/arcasleep/reporting/prediction_plot.py +224 -0
  49. arcasleep-0.1.1/core/src/arcasleep/reporting/summary.py +251 -0
  50. arcasleep-0.1.1/core/src/arcasleep/training/balanced.py +126 -0
  51. arcasleep-0.1.1/core/src/arcasleep/training/config.py +281 -0
  52. arcasleep-0.1.1/core/src/arcasleep/training/driver.py +267 -0
  53. arcasleep-0.1.1/core/src/arcasleep/training/folds.py +142 -0
  54. arcasleep-0.1.1/core/tests/test_balanced.py +25 -0
  55. arcasleep-0.1.1/core/tests/test_batching.py +43 -0
  56. arcasleep-0.1.1/core/tests/test_cli.py +14 -0
  57. arcasleep-0.1.1/core/tests/test_compare.py +350 -0
  58. arcasleep-0.1.1/core/tests/test_evaluate.py +699 -0
  59. arcasleep-0.1.1/core/tests/test_ggir.py +452 -0
  60. arcasleep-0.1.1/core/tests/test_models.py +15 -0
  61. arcasleep-0.1.1/core/tests/test_predict.py +130 -0
  62. arcasleep-0.1.1/core/tests/test_prediction_plot.py +107 -0
  63. arcasleep-0.1.1/core/tests/test_prepare_filter.py +21 -0
  64. arcasleep-0.1.1/core/tests/test_prepare_naming.py +50 -0
  65. arcasleep-0.1.1/core/tests/test_provenance.py +57 -0
  66. arcasleep-0.1.1/core/tests/test_pseudonyms.py +37 -0
  67. arcasleep-0.1.1/core/tests/test_splits.py +195 -0
  68. arcasleep-0.1.1/core/tests/test_staging_metrics.py +129 -0
  69. arcasleep-0.1.1/core/tests/test_summarize.py +240 -0
  70. arcasleep-0.1.1/core/tests/test_upload.py +89 -0
  71. arcasleep-0.1.1/pyproject.toml +112 -0
  72. arcasleep-0.1.1/setup.cfg +4 -0
  73. arcasleep-0.1.1/unet/README.md +73 -0
  74. arcasleep-0.1.1/unet/src/arcasleep_unet/__init__.py +1 -0
  75. arcasleep-0.1.1/unet/src/arcasleep_unet/family.py +89 -0
  76. arcasleep-0.1.1/unet/src/arcasleep_unet/model/__init__.py +8 -0
  77. arcasleep-0.1.1/unet/src/arcasleep_unet/model/definition.py +535 -0
  78. arcasleep-0.1.1/unet/src/arcasleep_unet/training.py +137 -0
  79. arcasleep-0.1.1/unet/tests/test_model.py +248 -0
  80. arcasleep-0.1.1/unet/tests/test_training.py +155 -0
@@ -0,0 +1,16 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ build/
8
+ *.egg-info/
9
+ results/
10
+ feature_cache/
11
+ *.safetensors
12
+ *.pisces
13
+ *.npz
14
+ arcasleep_pseudonym.key
15
+
16
+ plans/**
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arcascope Inc
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,15 @@
1
+ # setuptools_scm puts every Git-tracked file in the sdist. Only the packages,
2
+ # their tests and the project metadata belong there; run configs, split plans,
3
+ # cards, deployment files, CI and agent notes are repository material.
4
+ prune bidoze/cards
5
+ prune bidoze/config
6
+ prune bidoze/deploy
7
+ prune bidoze/docker
8
+ prune bidoze/scripts
9
+ prune unet/cards
10
+ prune unet/config
11
+ prune unet/scripts
12
+ prune .github
13
+ prune .claude
14
+ prune plans
15
+ exclude CLAUDE.md
@@ -0,0 +1,161 @@
1
+ Metadata-Version: 2.4
2
+ Name: arcasleep
3
+ Version: 0.1.1
4
+ Summary: Arcascope's open sleep-stage models: training, evaluation, release and inference
5
+ Author-email: Arcascope Inc <support@arcascope.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Arcascope/sleep-models
8
+ Project-URL: Repository, https://github.com/Arcascope/sleep-models
9
+ Project-URL: Issues, https://github.com/Arcascope/sleep-models/issues
10
+ Project-URL: Documentation, https://huggingface.co/arcascope
11
+ Keywords: sleep,actigraphy,accelerometer,sleep-staging,wearables
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Scientific/Engineering
19
+ Requires-Python: >=3.12
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Provides-Extra: pisces
23
+ Requires-Dist: pisces-lite>=4.1.1; extra == "pisces"
24
+ Provides-Extra: bidoze
25
+ Requires-Dist: jax; extra == "bidoze"
26
+ Requires-Dist: flax; extra == "bidoze"
27
+ Requires-Dist: optax; extra == "bidoze"
28
+ Provides-Extra: unet
29
+ Requires-Dist: jax; extra == "unet"
30
+ Requires-Dist: flax; extra == "unet"
31
+ Requires-Dist: optax; extra == "unet"
32
+ Provides-Extra: inference
33
+ Requires-Dist: jax; extra == "inference"
34
+ Requires-Dist: flax; extra == "inference"
35
+ Requires-Dist: pisces-lite[jax,proc]; extra == "inference"
36
+ Requires-Dist: arcasleep[pisces]; extra == "inference"
37
+ Requires-Dist: safetensors; extra == "inference"
38
+ Provides-Extra: hub
39
+ Requires-Dist: safetensors; extra == "hub"
40
+ Requires-Dist: huggingface_hub; extra == "hub"
41
+ Provides-Extra: prep
42
+ Requires-Dist: pisces-lite[proc]; extra == "prep"
43
+ Requires-Dist: arcasleep[pisces]; extra == "prep"
44
+ Provides-Extra: train
45
+ Requires-Dist: jax; extra == "train"
46
+ Requires-Dist: flax; extra == "train"
47
+ Requires-Dist: optax; extra == "train"
48
+ Requires-Dist: arcasleep[pisces]; extra == "train"
49
+ Requires-Dist: matplotlib; extra == "train"
50
+ Provides-Extra: report
51
+ Requires-Dist: matplotlib; extra == "report"
52
+ Requires-Dist: pandas; extra == "report"
53
+ Provides-Extra: aws
54
+ Requires-Dist: boto3>=1.34; extra == "aws"
55
+ Provides-Extra: publish
56
+ Requires-Dist: safetensors; extra == "publish"
57
+ Requires-Dist: matplotlib; extra == "publish"
58
+ Requires-Dist: pandas; extra == "publish"
59
+ Provides-Extra: preview
60
+ Requires-Dist: markdown-it-py>=3; extra == "preview"
61
+ Provides-Extra: all
62
+ Requires-Dist: arcasleep[aws,bidoze,hub,inference,prep,preview,publish,report,train,unet]; extra == "all"
63
+ Provides-Extra: dev
64
+ Requires-Dist: pytest>=8; extra == "dev"
65
+ Requires-Dist: ruff>=0.8; extra == "dev"
66
+ Dynamic: license-file
67
+
68
+ # Arcasleep
69
+
70
+ Arcascope's open source, open weights sleep models.
71
+
72
+ ---
73
+
74
+ One Python distribution, `arcasleep`, carries the shared data handling, training,
75
+ evaluation and release tooling (`core/`, the `arcasleep` import package) and
76
+ every model family (`bidoze/` and `unet/`, the `arcasleep_bidoze` and
77
+ `arcasleep_unet` import packages). Model
78
+ weights are released on the Hugging Face Hub, one repository per model variant.
79
+
80
+ ## Install
81
+
82
+ The base install is dependency-free: it provides the manifest tools and a
83
+ working CLI, and every other command imports its dependencies on demand.
84
+
85
+ ```bash
86
+ pip install arcasleep # CLI + manifest tools, no heavy deps
87
+ pip install "arcasleep[bidoze,inference,hub]" # run a released BiDoze model
88
+ pip install "arcasleep[unet,train]" # training stack (adds optax, matplotlib)
89
+ pip install "arcasleep[prep]" # build the feature cache
90
+ pip install "arcasleep[aws]" # S3 manifests and result upload
91
+ pip install "arcasleep[publish]" # build a release bundle
92
+ pip install "arcasleep[all]" # installs all extras
93
+ ```
94
+
95
+ `pisces-lite` and `arcascope-senpy` are public on PyPI; pisces-lite supplies
96
+ the dataset/IO layer and the metric registry, and its `[proc]` extra (pulled by
97
+ `[prep]`) the prebuilt senpy NUFFT wheel.
98
+
99
+ ## Commands
100
+
101
+ Every model family reads the same feature cache, so the cache and results
102
+ commands are shared; training, scoring and release sit under each family:
103
+
104
+ ```bash
105
+ arcasleep process # build the feature cache (needs [prep])
106
+ arcasleep splits-plan / splits-apply
107
+ arcasleep summarize # pool finished phases into a metrics_summary.csv
108
+ arcasleep compare # draw a metric grid across summaries
109
+ arcasleep hypnogram # hypnogram PNGs from prediction CSVs
110
+ arcasleep card-preview # render a built bundle's model card to HTML
111
+ arcasleep manifest-local / manifest-s3 / upload-results
112
+
113
+ arcasleep bidoze train # run the recipe from a feature cache
114
+ arcasleep bidoze evaluate # score a checkpoint on a cohort
115
+ arcasleep bidoze publish # build a safetensors release bundle, optionally upload it
116
+ arcasleep bidoze predict # per-epoch stages for raw accelerometer files
117
+
118
+ arcasleep unet train | evaluate | publish | predict
119
+ ```
120
+
121
+ ## Models
122
+
123
+ The current pediatric model variants are trained on the clinical pediatric pool described in [Weaver et al. 2026](https://pubmed.ncbi.nlm.nih.gov/40676371/). This set has subjects with no recorded diagnosis (n=37), as well as mild (n=94), moderate (n=33), and severe (n=38) obstructive sleep apnea (OSA). We are grateful to Glenn Weaver and his group for sharing their data with us.
124
+
125
+ ### BiDoze
126
+
127
+ Published on Hugging Face as [`arcascope/arcasleep-bidoze-pediatric`](https://huggingface.co/arcascope/arcasleep-bidoze-pediatric); the model lives in [`bidoze/`](bidoze/).
128
+
129
+ Wake/Light/Deep/REM predictions, plus a 5th head for identifying gaps in accelerometer.
130
+
131
+ 1. **Architecture:** `[CNN encoder] -> [ALiBi Transformers] -> [5-head MLP]`.
132
+ 2. Developed via a semi-autonomous research loop using LLMs.
133
+ 1. Agents were given the goal to optimize model architecture and training regime with fixed train/test splits.
134
+ 2. "Best" as measured by the geometric mean of TST and WASO MAPE.
135
+
136
+ ## UNet
137
+
138
+ Published on Hugging Face as [`arcascope/arcasleep-unet-pediatric`](https://huggingface.co/arcascope/arcasleep-unet-pediatric); the model lives in [`unet/`](unet/).
139
+
140
+ Wake/Light/Deep/REM predictions, plus a 5th head for identifying gaps in accelerometer.
141
+
142
+ 1. **Architecture:** the temporal U-Net described in Olsen et al., "A flexible deep learning architecture for temporal sleep stage classification using accelerometry and photoplethysmography," IEEE TBME 2022 ([doi:10.1109/TBME.2022.3187945](https://doi.org/10.1109/TBME.2022.3187945)), over raw 2-s spectrogram frames.
143
+ 2. Trained with the paper's procedure: class-balanced segment sampling and loss, early stopping on held-out subjects.
144
+
145
+ ## Releasing the package
146
+
147
+ The distribution is published to PyPI from CI with
148
+ [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): no API
149
+ token is stored. `.github/workflows/release.yml` builds sdist + wheel from the
150
+ repository root, tests the built wheel, and publishes when a GitHub Release is
151
+ published for an `arcasleep-vX.Y.Z` tag.
152
+
153
+ The tag is the source of truth for the version: `setuptools-scm` reads the
154
+ nearest `arcasleep-vX.Y.Z` tag (configured in `pyproject.toml`), so the
155
+ distribution version and the release tag cannot drift. To release, push an
156
+ `arcasleep-vX.Y.Z` tag and publish a GitHub Release for it -- there is no
157
+ version literal to edit. The workflow fails if the tag and the built version
158
+ disagree. A manual `workflow_dispatch` runs the build and wheel tests without
159
+ publishing; commits past a tag build as the next patch dev version
160
+ (`X.Y.(Z+1).devN`), which is what `.github/workflows/dry-run-testpypi.yml`
161
+ rehearses against TestPyPI.
@@ -0,0 +1,94 @@
1
+ # Arcasleep
2
+
3
+ Arcascope's open source, open weights sleep models.
4
+
5
+ ---
6
+
7
+ One Python distribution, `arcasleep`, carries the shared data handling, training,
8
+ evaluation and release tooling (`core/`, the `arcasleep` import package) and
9
+ every model family (`bidoze/` and `unet/`, the `arcasleep_bidoze` and
10
+ `arcasleep_unet` import packages). Model
11
+ weights are released on the Hugging Face Hub, one repository per model variant.
12
+
13
+ ## Install
14
+
15
+ The base install is dependency-free: it provides the manifest tools and a
16
+ working CLI, and every other command imports its dependencies on demand.
17
+
18
+ ```bash
19
+ pip install arcasleep # CLI + manifest tools, no heavy deps
20
+ pip install "arcasleep[bidoze,inference,hub]" # run a released BiDoze model
21
+ pip install "arcasleep[unet,train]" # training stack (adds optax, matplotlib)
22
+ pip install "arcasleep[prep]" # build the feature cache
23
+ pip install "arcasleep[aws]" # S3 manifests and result upload
24
+ pip install "arcasleep[publish]" # build a release bundle
25
+ pip install "arcasleep[all]" # installs all extras
26
+ ```
27
+
28
+ `pisces-lite` and `arcascope-senpy` are public on PyPI; pisces-lite supplies
29
+ the dataset/IO layer and the metric registry, and its `[proc]` extra (pulled by
30
+ `[prep]`) the prebuilt senpy NUFFT wheel.
31
+
32
+ ## Commands
33
+
34
+ Every model family reads the same feature cache, so the cache and results
35
+ commands are shared; training, scoring and release sit under each family:
36
+
37
+ ```bash
38
+ arcasleep process # build the feature cache (needs [prep])
39
+ arcasleep splits-plan / splits-apply
40
+ arcasleep summarize # pool finished phases into a metrics_summary.csv
41
+ arcasleep compare # draw a metric grid across summaries
42
+ arcasleep hypnogram # hypnogram PNGs from prediction CSVs
43
+ arcasleep card-preview # render a built bundle's model card to HTML
44
+ arcasleep manifest-local / manifest-s3 / upload-results
45
+
46
+ arcasleep bidoze train # run the recipe from a feature cache
47
+ arcasleep bidoze evaluate # score a checkpoint on a cohort
48
+ arcasleep bidoze publish # build a safetensors release bundle, optionally upload it
49
+ arcasleep bidoze predict # per-epoch stages for raw accelerometer files
50
+
51
+ arcasleep unet train | evaluate | publish | predict
52
+ ```
53
+
54
+ ## Models
55
+
56
+ The current pediatric model variants are trained on the clinical pediatric pool described in [Weaver et al. 2026](https://pubmed.ncbi.nlm.nih.gov/40676371/). This set has subjects with no recorded diagnosis (n=37), as well as mild (n=94), moderate (n=33), and severe (n=38) obstructive sleep apnea (OSA). We are grateful to Glenn Weaver and his group for sharing their data with us.
57
+
58
+ ### BiDoze
59
+
60
+ Published on Hugging Face as [`arcascope/arcasleep-bidoze-pediatric`](https://huggingface.co/arcascope/arcasleep-bidoze-pediatric); the model lives in [`bidoze/`](bidoze/).
61
+
62
+ Wake/Light/Deep/REM predictions, plus a 5th head for identifying gaps in accelerometer.
63
+
64
+ 1. **Architecture:** `[CNN encoder] -> [ALiBi Transformers] -> [5-head MLP]`.
65
+ 2. Developed via a semi-autonomous research loop using LLMs.
66
+ 1. Agents were given the goal to optimize model architecture and training regime with fixed train/test splits.
67
+ 2. "Best" as measured by the geometric mean of TST and WASO MAPE.
68
+
69
+ ## UNet
70
+
71
+ Published on Hugging Face as [`arcascope/arcasleep-unet-pediatric`](https://huggingface.co/arcascope/arcasleep-unet-pediatric); the model lives in [`unet/`](unet/).
72
+
73
+ Wake/Light/Deep/REM predictions, plus a 5th head for identifying gaps in accelerometer.
74
+
75
+ 1. **Architecture:** the temporal U-Net described in Olsen et al., "A flexible deep learning architecture for temporal sleep stage classification using accelerometry and photoplethysmography," IEEE TBME 2022 ([doi:10.1109/TBME.2022.3187945](https://doi.org/10.1109/TBME.2022.3187945)), over raw 2-s spectrogram frames.
76
+ 2. Trained with the paper's procedure: class-balanced segment sampling and loss, early stopping on held-out subjects.
77
+
78
+ ## Releasing the package
79
+
80
+ The distribution is published to PyPI from CI with
81
+ [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): no API
82
+ token is stored. `.github/workflows/release.yml` builds sdist + wheel from the
83
+ repository root, tests the built wheel, and publishes when a GitHub Release is
84
+ published for an `arcasleep-vX.Y.Z` tag.
85
+
86
+ The tag is the source of truth for the version: `setuptools-scm` reads the
87
+ nearest `arcasleep-vX.Y.Z` tag (configured in `pyproject.toml`), so the
88
+ distribution version and the release tag cannot drift. To release, push an
89
+ `arcasleep-vX.Y.Z` tag and publish a GitHub Release for it -- there is no
90
+ version literal to edit. The workflow fails if the tag and the built version
91
+ disagree. A manual `workflow_dispatch` runs the build and wheel tests without
92
+ publishing; commits past a tag build as the next patch dev version
93
+ (`X.Y.(Z+1).devN`), which is what `.github/workflows/dry-run-testpypi.yml`
94
+ rehearses against TestPyPI.
@@ -0,0 +1,161 @@
1
+ Metadata-Version: 2.4
2
+ Name: arcasleep
3
+ Version: 0.1.1
4
+ Summary: Arcascope's open sleep-stage models: training, evaluation, release and inference
5
+ Author-email: Arcascope Inc <support@arcascope.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Arcascope/sleep-models
8
+ Project-URL: Repository, https://github.com/Arcascope/sleep-models
9
+ Project-URL: Issues, https://github.com/Arcascope/sleep-models/issues
10
+ Project-URL: Documentation, https://huggingface.co/arcascope
11
+ Keywords: sleep,actigraphy,accelerometer,sleep-staging,wearables
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Scientific/Engineering
19
+ Requires-Python: >=3.12
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Provides-Extra: pisces
23
+ Requires-Dist: pisces-lite>=4.1.1; extra == "pisces"
24
+ Provides-Extra: bidoze
25
+ Requires-Dist: jax; extra == "bidoze"
26
+ Requires-Dist: flax; extra == "bidoze"
27
+ Requires-Dist: optax; extra == "bidoze"
28
+ Provides-Extra: unet
29
+ Requires-Dist: jax; extra == "unet"
30
+ Requires-Dist: flax; extra == "unet"
31
+ Requires-Dist: optax; extra == "unet"
32
+ Provides-Extra: inference
33
+ Requires-Dist: jax; extra == "inference"
34
+ Requires-Dist: flax; extra == "inference"
35
+ Requires-Dist: pisces-lite[jax,proc]; extra == "inference"
36
+ Requires-Dist: arcasleep[pisces]; extra == "inference"
37
+ Requires-Dist: safetensors; extra == "inference"
38
+ Provides-Extra: hub
39
+ Requires-Dist: safetensors; extra == "hub"
40
+ Requires-Dist: huggingface_hub; extra == "hub"
41
+ Provides-Extra: prep
42
+ Requires-Dist: pisces-lite[proc]; extra == "prep"
43
+ Requires-Dist: arcasleep[pisces]; extra == "prep"
44
+ Provides-Extra: train
45
+ Requires-Dist: jax; extra == "train"
46
+ Requires-Dist: flax; extra == "train"
47
+ Requires-Dist: optax; extra == "train"
48
+ Requires-Dist: arcasleep[pisces]; extra == "train"
49
+ Requires-Dist: matplotlib; extra == "train"
50
+ Provides-Extra: report
51
+ Requires-Dist: matplotlib; extra == "report"
52
+ Requires-Dist: pandas; extra == "report"
53
+ Provides-Extra: aws
54
+ Requires-Dist: boto3>=1.34; extra == "aws"
55
+ Provides-Extra: publish
56
+ Requires-Dist: safetensors; extra == "publish"
57
+ Requires-Dist: matplotlib; extra == "publish"
58
+ Requires-Dist: pandas; extra == "publish"
59
+ Provides-Extra: preview
60
+ Requires-Dist: markdown-it-py>=3; extra == "preview"
61
+ Provides-Extra: all
62
+ Requires-Dist: arcasleep[aws,bidoze,hub,inference,prep,preview,publish,report,train,unet]; extra == "all"
63
+ Provides-Extra: dev
64
+ Requires-Dist: pytest>=8; extra == "dev"
65
+ Requires-Dist: ruff>=0.8; extra == "dev"
66
+ Dynamic: license-file
67
+
68
+ # Arcasleep
69
+
70
+ Arcascope's open source, open weights sleep models.
71
+
72
+ ---
73
+
74
+ One Python distribution, `arcasleep`, carries the shared data handling, training,
75
+ evaluation and release tooling (`core/`, the `arcasleep` import package) and
76
+ every model family (`bidoze/` and `unet/`, the `arcasleep_bidoze` and
77
+ `arcasleep_unet` import packages). Model
78
+ weights are released on the Hugging Face Hub, one repository per model variant.
79
+
80
+ ## Install
81
+
82
+ The base install is dependency-free: it provides the manifest tools and a
83
+ working CLI, and every other command imports its dependencies on demand.
84
+
85
+ ```bash
86
+ pip install arcasleep # CLI + manifest tools, no heavy deps
87
+ pip install "arcasleep[bidoze,inference,hub]" # run a released BiDoze model
88
+ pip install "arcasleep[unet,train]" # training stack (adds optax, matplotlib)
89
+ pip install "arcasleep[prep]" # build the feature cache
90
+ pip install "arcasleep[aws]" # S3 manifests and result upload
91
+ pip install "arcasleep[publish]" # build a release bundle
92
+ pip install "arcasleep[all]" # installs all extras
93
+ ```
94
+
95
+ `pisces-lite` and `arcascope-senpy` are public on PyPI; pisces-lite supplies
96
+ the dataset/IO layer and the metric registry, and its `[proc]` extra (pulled by
97
+ `[prep]`) the prebuilt senpy NUFFT wheel.
98
+
99
+ ## Commands
100
+
101
+ Every model family reads the same feature cache, so the cache and results
102
+ commands are shared; training, scoring and release sit under each family:
103
+
104
+ ```bash
105
+ arcasleep process # build the feature cache (needs [prep])
106
+ arcasleep splits-plan / splits-apply
107
+ arcasleep summarize # pool finished phases into a metrics_summary.csv
108
+ arcasleep compare # draw a metric grid across summaries
109
+ arcasleep hypnogram # hypnogram PNGs from prediction CSVs
110
+ arcasleep card-preview # render a built bundle's model card to HTML
111
+ arcasleep manifest-local / manifest-s3 / upload-results
112
+
113
+ arcasleep bidoze train # run the recipe from a feature cache
114
+ arcasleep bidoze evaluate # score a checkpoint on a cohort
115
+ arcasleep bidoze publish # build a safetensors release bundle, optionally upload it
116
+ arcasleep bidoze predict # per-epoch stages for raw accelerometer files
117
+
118
+ arcasleep unet train | evaluate | publish | predict
119
+ ```
120
+
121
+ ## Models
122
+
123
+ The current pediatric model variants are trained on the clinical pediatric pool described in [Weaver et al. 2026](https://pubmed.ncbi.nlm.nih.gov/40676371/). This set has subjects with no recorded diagnosis (n=37), as well as mild (n=94), moderate (n=33), and severe (n=38) obstructive sleep apnea (OSA). We are grateful to Glenn Weaver and his group for sharing their data with us.
124
+
125
+ ### BiDoze
126
+
127
+ Published on Hugging Face as [`arcascope/arcasleep-bidoze-pediatric`](https://huggingface.co/arcascope/arcasleep-bidoze-pediatric); the model lives in [`bidoze/`](bidoze/).
128
+
129
+ Wake/Light/Deep/REM predictions, plus a 5th head for identifying gaps in accelerometer.
130
+
131
+ 1. **Architecture:** `[CNN encoder] -> [ALiBi Transformers] -> [5-head MLP]`.
132
+ 2. Developed via a semi-autonomous research loop using LLMs.
133
+ 1. Agents were given the goal to optimize model architecture and training regime with fixed train/test splits.
134
+ 2. "Best" as measured by the geometric mean of TST and WASO MAPE.
135
+
136
+ ## UNet
137
+
138
+ Published on Hugging Face as [`arcascope/arcasleep-unet-pediatric`](https://huggingface.co/arcascope/arcasleep-unet-pediatric); the model lives in [`unet/`](unet/).
139
+
140
+ Wake/Light/Deep/REM predictions, plus a 5th head for identifying gaps in accelerometer.
141
+
142
+ 1. **Architecture:** the temporal U-Net described in Olsen et al., "A flexible deep learning architecture for temporal sleep stage classification using accelerometry and photoplethysmography," IEEE TBME 2022 ([doi:10.1109/TBME.2022.3187945](https://doi.org/10.1109/TBME.2022.3187945)), over raw 2-s spectrogram frames.
143
+ 2. Trained with the paper's procedure: class-balanced segment sampling and loss, early stopping on held-out subjects.
144
+
145
+ ## Releasing the package
146
+
147
+ The distribution is published to PyPI from CI with
148
+ [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): no API
149
+ token is stored. `.github/workflows/release.yml` builds sdist + wheel from the
150
+ repository root, tests the built wheel, and publishes when a GitHub Release is
151
+ published for an `arcasleep-vX.Y.Z` tag.
152
+
153
+ The tag is the source of truth for the version: `setuptools-scm` reads the
154
+ nearest `arcasleep-vX.Y.Z` tag (configured in `pyproject.toml`), so the
155
+ distribution version and the release tag cannot drift. To release, push an
156
+ `arcasleep-vX.Y.Z` tag and publish a GitHub Release for it -- there is no
157
+ version literal to edit. The workflow fails if the tag and the built version
158
+ disagree. A manual `workflow_dispatch` runs the build and wheel tests without
159
+ publishing; commits past a tag build as the next patch dev version
160
+ (`X.Y.(Z+1).devN`), which is what `.github/workflows/dry-run-testpypi.yml`
161
+ rehearses against TestPyPI.
@@ -0,0 +1,78 @@
1
+ .gitignore
2
+ LICENSE
3
+ MANIFEST.in
4
+ README.md
5
+ pyproject.toml
6
+ arcasleep.egg-info/PKG-INFO
7
+ arcasleep.egg-info/SOURCES.txt
8
+ arcasleep.egg-info/dependency_links.txt
9
+ arcasleep.egg-info/entry_points.txt
10
+ arcasleep.egg-info/requires.txt
11
+ arcasleep.egg-info/scm_file_list.json
12
+ arcasleep.egg-info/scm_version.json
13
+ arcasleep.egg-info/top_level.txt
14
+ bidoze/README.md
15
+ bidoze/src/arcasleep_bidoze/__init__.py
16
+ bidoze/src/arcasleep_bidoze/family.py
17
+ bidoze/src/arcasleep_bidoze/training.py
18
+ bidoze/src/arcasleep_bidoze/model/__init__.py
19
+ bidoze/src/arcasleep_bidoze/model/constants.py
20
+ bidoze/src/arcasleep_bidoze/model/definition.py
21
+ bidoze/tests/test_balanced_recipe.py
22
+ bidoze/tests/test_curriculum_schedule.py
23
+ bidoze/tests/test_live_model.py
24
+ bidoze/tests/test_publish.py
25
+ core/src/arcasleep/__init__.py
26
+ core/src/arcasleep/cli.py
27
+ core/src/arcasleep/ggir.py
28
+ core/src/arcasleep/models.py
29
+ core/src/arcasleep/predict.py
30
+ core/src/arcasleep/artifacts/__init__.py
31
+ core/src/arcasleep/artifacts/provenance.py
32
+ core/src/arcasleep/artifacts/publish.py
33
+ core/src/arcasleep/artifacts/upload.py
34
+ core/src/arcasleep/artifacts/templates/quickstart.md
35
+ core/src/arcasleep/data/batching.py
36
+ core/src/arcasleep/data/bundle.py
37
+ core/src/arcasleep/data/cache.py
38
+ core/src/arcasleep/data/constants.py
39
+ core/src/arcasleep/data/prepare.py
40
+ core/src/arcasleep/data/pseudonyms.py
41
+ core/src/arcasleep/data/splits.py
42
+ core/src/arcasleep/evaluation/__init__.py
43
+ core/src/arcasleep/evaluation/run.py
44
+ core/src/arcasleep/evaluation/staging_metrics.py
45
+ core/src/arcasleep/reporting/__init__.py
46
+ core/src/arcasleep/reporting/compare.py
47
+ core/src/arcasleep/reporting/hypnogram.py
48
+ core/src/arcasleep/reporting/prediction_plot.py
49
+ core/src/arcasleep/reporting/summary.py
50
+ core/src/arcasleep/training/balanced.py
51
+ core/src/arcasleep/training/config.py
52
+ core/src/arcasleep/training/driver.py
53
+ core/src/arcasleep/training/folds.py
54
+ core/tests/test_balanced.py
55
+ core/tests/test_batching.py
56
+ core/tests/test_cli.py
57
+ core/tests/test_compare.py
58
+ core/tests/test_evaluate.py
59
+ core/tests/test_ggir.py
60
+ core/tests/test_models.py
61
+ core/tests/test_predict.py
62
+ core/tests/test_prediction_plot.py
63
+ core/tests/test_prepare_filter.py
64
+ core/tests/test_prepare_naming.py
65
+ core/tests/test_provenance.py
66
+ core/tests/test_pseudonyms.py
67
+ core/tests/test_splits.py
68
+ core/tests/test_staging_metrics.py
69
+ core/tests/test_summarize.py
70
+ core/tests/test_upload.py
71
+ unet/README.md
72
+ unet/src/arcasleep_unet/__init__.py
73
+ unet/src/arcasleep_unet/family.py
74
+ unet/src/arcasleep_unet/training.py
75
+ unet/src/arcasleep_unet/model/__init__.py
76
+ unet/src/arcasleep_unet/model/definition.py
77
+ unet/tests/test_model.py
78
+ unet/tests/test_training.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ arcasleep = arcasleep.cli:main
@@ -0,0 +1,57 @@
1
+
2
+ [all]
3
+ arcasleep[aws,bidoze,hub,inference,prep,preview,publish,report,train,unet]
4
+
5
+ [aws]
6
+ boto3>=1.34
7
+
8
+ [bidoze]
9
+ jax
10
+ flax
11
+ optax
12
+
13
+ [dev]
14
+ pytest>=8
15
+ ruff>=0.8
16
+
17
+ [hub]
18
+ safetensors
19
+ huggingface_hub
20
+
21
+ [inference]
22
+ jax
23
+ flax
24
+ pisces-lite[jax,proc]
25
+ arcasleep[pisces]
26
+ safetensors
27
+
28
+ [pisces]
29
+ pisces-lite>=4.1.1
30
+
31
+ [prep]
32
+ pisces-lite[proc]
33
+ arcasleep[pisces]
34
+
35
+ [preview]
36
+ markdown-it-py>=3
37
+
38
+ [publish]
39
+ safetensors
40
+ matplotlib
41
+ pandas
42
+
43
+ [report]
44
+ matplotlib
45
+ pandas
46
+
47
+ [train]
48
+ jax
49
+ flax
50
+ optax
51
+ arcasleep[pisces]
52
+ matplotlib
53
+
54
+ [unet]
55
+ jax
56
+ flax
57
+ optax