[\s\S]*?<\/div>/, "");
- raw = normalizeMarkdown(raw);
- const page = convertPage(raw, rel, { state, base: "/sleepkit" });
- let text = page.text
- .replace(/#only-light/g, "#only-light")
- .replace(//g, "
"); - if (rel === "index.md") - text = text.replace( - /^description:.*$/m, - 'description: \"AI development kit for sleep monitoring on Ambiq devices.\"', - ); - if (intro) text = text.replace(/^description:.*$/m, (line) => `${line}\nhero:\n tagline: ${JSON.stringify(intro)}`); - let blockIndex = 0; - text = text.replace( - /^([ \t]*)(`{3,})([\w+-]+)([^\n]*)\n([\s\S]*?)^\1\2[ \t]*$/gm, - (all, indent, fence, lang, meta, body) => { - if (["mermaid", "text"].includes(lang)) return all; - const extension = - { - python: "py", - py: "py", - bash: "sh", - sh: "sh", - console: "sh", - json: "json", - jsonc: "jsonc", - yaml: "yaml", - yml: "yaml", - }[lang] || lang; - const code = body - .split("\n") - .map((l) => (l.startsWith(indent) ? l.slice(indent.length) : l)) - .join("\n") - .trimEnd(); - if (lang === "json") { - try { - JSON.parse(code); - } catch (error) { - throw new Error(`Invalid JSON example in ${rel}: ${error.message}`); - } - } - if (meta.includes("fragment")) - return `${indent}${fence}${lang} title="Configuration fragment"\n${body}${indent}${fence}`; - const lines = code.split("\n").length; - const name = `${rel.replace(/\.md$/, "").replaceAll("/", "-")}-${++blockIndex}.${extension}`; - if ( - (["json", "jsonc", "yaml", "yml"].includes(lang) && lines > 16) || - (["py", "python"].includes(lang) && lines > 45) - ) { - mkdirSync("public/examples", { recursive: true }); - writeFileSync("public/examples/" + name, code + "\n"); - return `${indent}\n\n${indent}${fence}${lang} title="${name}"\n${body}${indent}${fence}\n\n${indent} `;
- }
- const title =
- lang === "py" || lang === "python"
- ? "Python example"
- : ["bash", "sh", "console"].includes(lang)
- ? "Terminal"
- : lang.toUpperCase() + " example";
- return `${indent}${fence}${lang}${meta.includes("title=") ? meta : ' title="' + title + '"' + meta}\n${body}${indent}${fence}`;
- },
- );
- if (text.includes(" readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+ entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)],
+);
+rmSync("public/examples", { recursive: true, force: true });
+mkdirSync("public/examples", { recursive: true });
+const downloads = new Map();
+for (const file of walk("src/content/docs").filter((path) => path.endsWith(".mdx"))) {
+ const source = readFileSync(file, "utf8");
+ for (const match of source.matchAll(/Download notebook View source Open in Colab
',
diff --git a/astro-site/scripts/build-reference.mjs b/astro-site/scripts/build-reference.mjs
index 43a2de7..148e6b7 100644
--- a/astro-site/scripts/build-reference.mjs
+++ b/astro-site/scripts/build-reference.mjs
@@ -12,6 +12,8 @@ const run = (cmd, args) =>
rmSync("public/reference", { recursive: true, force: true });
const commit = run("git", ["rev-parse", "HEAD"]).trim();
mkdirSync(".cache", { recursive: true });
+mkdirSync("src/data", { recursive: true });
+rmSync("src/content/docs/reference/api", { recursive: true, force: true });
const dump = JSON.parse(
run("uv", [
"tool",
@@ -107,14 +109,13 @@ writeFileSync(
);
writeFileSync(
"src/data/redirects.json",
- JSON.stringify(
- Object.fromEntries(
- modules.map((m) => [
- "/api/" + m.path.replaceAll(".", "/"),
- "/sleepkit/" + route(m) + "/",
- ]),
- ),
- ),
+ JSON.stringify({
+ ...JSON.parse(readFileSync("src/redirects.json", "utf8")),
+ ...Object.fromEntries(modules.map((m) => [
+ "/api/" + m.path.replaceAll(".", "/"),
+ "/sleepkit/" + route(m) + "/",
+ ])),
+ }),
);
writeFileSync(
"src/content/docs/reference/index.mdx",
diff --git a/astro-site/scripts/canonical-content.test.mjs b/astro-site/scripts/canonical-content.test.mjs
new file mode 100644
index 0000000..9926aa5
--- /dev/null
+++ b/astro-site/scripts/canonical-content.test.mjs
@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import test from "node:test";
+
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+ entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)],
+);
+const snapshot = () => Object.fromEntries([
+ ...walk("src/content/docs").filter((p) => p.endsWith(".mdx") && !p.startsWith("src/content/docs/reference/")),
+ "src/navigation.mjs", "src/redirects.json",
+ ...walk("public").filter((p) => !/^public\/(reference|notebooks|examples|evidence)\//.test(p)),
+].map((p) => [relative(".", p), readFileSync(p).toString("base64")]));
+
+test("generation preserves authored pages, navigation, redirects and static assets", () => {
+ const before = snapshot();
+ assert(Object.keys(before).length > 40, "Missing canonical content");
+ execFileSync("npm", ["run", "prepare:docs"], { stdio: "pipe" });
+ assert.deepEqual(snapshot(), before);
+});
diff --git a/astro-site/scripts/check-doc-examples.py b/astro-site/scripts/check-doc-examples.py
index 217871d..1ea0cc8 100644
--- a/astro-site/scripts/check-doc-examples.py
+++ b/astro-site/scripts/check-doc-examples.py
@@ -10,7 +10,7 @@
tree = ast.parse((root / "sleepkit/features" / f"{name}.py").read_text())
function = next(n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.name == "feature_names")
names = ast.literal_eval(next(n.value for n in ast.walk(function) if isinstance(n, ast.Return)))
- doc = (root / "docs/features" / f"{name}.md").read_text()
+ doc = (root / "astro-site/src/content/docs/features" / f"{name}.mdx").read_text()
table = re.findall(r"^\| (\w+) \|", doc, re.MULTILINE)
assert table == names, f"{name}: feature table does not match feature_names()"
paths = {
@@ -33,7 +33,7 @@
"modes/demo.md",
"datasets/cmidss.md",
]:
- text = (root / "docs" / rel).read_text()
+ text = (root / "astro-site/src/content/docs" / (rel + "x")).read_text()
for match in re.finditer(r"^([ \t]*)```(?:py|python)(?:[^\n]*)\n(.*?)^\1```", text, re.MULTILINE | re.DOTALL):
ast.parse(textwrap.dedent(match[2]))
print("Verified feature tables, HDF5 paths and updated Python example syntax.")
diff --git a/astro-site/scripts/check-output.mjs b/astro-site/scripts/check-output.mjs
index 563a0f0..8f4ae60 100644
--- a/astro-site/scripts/check-output.mjs
+++ b/astro-site/scripts/check-output.mjs
@@ -71,18 +71,13 @@ console.log(
`Verified internal links across ${cache.size} pages, ${index.rows.length} API symbols and discovery exports.`,
);
-for (const path of files(resolve("../docs")).filter(
- (p) => p.endsWith(".md") && !p.includes("/assets/"),
-)) {
- const rel = relative(resolve("../docs"), path).replace(/(?:index)?\.md$/, "");
- if (internalPages.has(relative(resolve("../docs"), path))) {
- assert(!existsSync(join(root, rel, "index.html")), `Internal page published: ${rel}`);
- continue;
- }
- assert(
- existsSync(join(root, rel, "index.html")),
- `Missing authored route: ${rel}`,
- );
+for (const path of files(resolve("src/content/docs")).filter((p) => /\.mdx?$/.test(p))) {
+ const rel = relative(resolve("src/content/docs"), path).replace(/(?:index)?\.mdx?$/, "");
+ assert(existsSync(join(root, rel, "index.html")), `Missing authored route: ${rel}`);
+}
+for (const path of internalPages) {
+ const rel = path.replace(/(?:index)?\.md$/, "");
+ assert(!existsSync(join(root, rel, "index.html")), `Internal page published: ${rel}`);
}
const notebook = JSON.parse(
readFileSync("../notebooks/train-detect-model.ipynb", "utf8"),
@@ -202,10 +197,21 @@ assert(
"Notebook duplicates the page title",
);
assert.deepEqual(
- readFileSync("../docs/guides/train-detect-model.ipynb"),
+ readFileSync("../notebooks/archive/previous-docs-train-detect-model.ipynb"),
readFileSync("dist/notebooks/previous-docs-train-detect-model.ipynb"),
);
assert(
!existsSync("public/examples/models-index-1.json"),
"Model fragment should not be offered as a runnable configuration",
);
+
+for (const path of files(resolve("../notebooks")).filter((p) => p.endsWith(".ipynb"))) {
+ const notebook = JSON.parse(readFileSync(path, "utf8"));
+ for (const cell of notebook.cells) {
+ if (cell.cell_type !== "markdown") continue;
+ const source = Array.isArray(cell.source) ? cell.source.join("") : cell.source;
+ for (const match of source.matchAll(/(?:github\.com|github)\/AmbiqAI\/sleepkit\/blob\/main\/([^\s)"<>]+)/g)) {
+ assert(existsSync(resolve("..", match[1])), `Notebook source link is missing: ${path} -> ${match[1]}`);
+ }
+ }
+}
diff --git a/astro-site/scripts/normalize-markdown.mjs b/astro-site/scripts/normalize-markdown.mjs
deleted file mode 100644
index 98605fe..0000000
--- a/astro-site/scripts/normalize-markdown.mjs
+++ /dev/null
@@ -1,90 +0,0 @@
-/** Normalize Material block syntax before the shared MDX converter runs. */
-export function normalizeMarkdown(text) {
- const lines = text.split("\n");
- function blocks(input) {
- const out = [];
- let fence;
- for (let i = 0; i < input.length; i++) {
- const line = input[i];
- const token = line.match(/^\s*(`{3,}|~{3,})/);
- if (token) {
- if (!fence) fence = token[1];
- else if (token[1].startsWith(fence)) fence = undefined;
- out.push(line);
- continue;
- }
- if (fence) {
- out.push(line);
- continue;
- }
- const match = line.match(
- /^([ \t]*)(!!!|\?\?\?\+?)\s+([\w-]+)(?:\s+(.*))?$/,
- );
- if (match) {
- const [, indent, marker, rawType, rawTitle = ""] = match;
- const type = rawType.toLowerCase();
- const title = rawTitle.replace(/^["']|["']$/g, "");
- const body = [];
- let j = i + 1;
- while (
- j < input.length &&
- (!input[j].trim() || input[j].startsWith(indent + " "))
- ) {
- body.push(input[j].trim() ? input[j].slice(indent.length + 4) : "");
- j++;
- }
- const inner = blocks(body).join("\n").trim();
- if (marker.startsWith("???")) {
- const label = title || type[0].toUpperCase() + type.slice(1);
- out.push(
- "",
- `${indent}"); - if (rel === "index.md") - text = text.replace( - /^description:.*$/m, - 'description: \"AI development kit for sleep monitoring on Ambiq devices.\"', - ); - if (intro) text = text.replace(/^description:.*$/m, (line) => `${line}\nhero:\n tagline: ${JSON.stringify(intro)}`); - let blockIndex = 0; - text = text.replace( - /^([ \t]*)(`{3,})([\w+-]+)([^\n]*)\n([\s\S]*?)^\1\2[ \t]*$/gm, - (all, indent, fence, lang, meta, body) => { - if (["mermaid", "text"].includes(lang)) return all; - const extension = - { - python: "py", - py: "py", - bash: "sh", - sh: "sh", - console: "sh", - json: "json", - jsonc: "jsonc", - yaml: "yaml", - yml: "yaml", - }[lang] || lang; - const code = body - .split("\n") - .map((l) => (l.startsWith(indent) ? l.slice(indent.length) : l)) - .join("\n") - .trimEnd(); - if (lang === "json") { - try { - JSON.parse(code); - } catch (error) { - throw new Error(`Invalid JSON example in ${rel}: ${error.message}`); - } - } - if (meta.includes("fragment")) - return `${indent}${fence}${lang} title="Configuration fragment"\n${body}${indent}${fence}`; - const lines = code.split("\n").length; - const name = `${rel.replace(/\.md$/, "").replaceAll("/", "-")}-${++blockIndex}.${extension}`; - if ( - (["json", "jsonc", "yaml", "yml"].includes(lang) && lines > 16) || - (["py", "python"].includes(lang) && lines > 45) - ) { - mkdirSync("public/examples", { recursive: true }); - writeFileSync("public/examples/" + name, code + "\n"); - return `${indent}
"));
- assert(closed.includes("
Advanced
")); - assert( - convert('# Test\n\n???+ note "Expanded"\n\n Detail.').includes( - "",
- ),
- );
-});
-test("image attributes become image properties; code samples remain verbatim", () => {
- const image = normalizeMarkdown('{ width="540" }');
- assert.equal(image, '
');
- const fenced = '```text\n!!! Example\n{ width="540" }\n```';
- assert.equal(normalizeMarkdown(fenced), fenced);
-});
diff --git a/docs/datasets/byod.md b/astro-site/src/content/docs/datasets/byod.mdx
similarity index 87%
rename from docs/datasets/byod.md
rename to astro-site/src/content/docs/datasets/byod.mdx
index 0edc66e..0525a8c 100644
--- a/docs/datasets/byod.md
+++ b/astro-site/src/content/docs/datasets/byod.mdx
@@ -1,12 +1,15 @@
-# Bring-Your-Own-Dataset (BYOD)
+---
+title: "Bring-Your-Own-Dataset (BYOD)"
+description: "A custom dataset subclasses sk.Dataset, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal…"
+---
-A custom dataset subclasses `sk.Dataset`, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal signal schema: pair the adapter with a [custom feature set](../features/byofs.md).
+A custom dataset subclasses `sk.Dataset`, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal signal schema: pair the adapter with a [custom feature set](/sleepkit/features/byofs/).
## Define the adapter
This example reads an existing directory of subject `.npz` files with a `signal` array. It makes an explicit subject split and does not download or invent data.
-```python
+```python title="Python example"
from pathlib import Path
import random
import numpy as np
diff --git a/docs/datasets/cmidss.md b/astro-site/src/content/docs/datasets/cmidss.mdx
similarity index 80%
rename from docs/datasets/cmidss.md
rename to astro-site/src/content/docs/datasets/cmidss.mdx
index 41ff5d6..7c38c73 100644
--- a/docs/datasets/cmidss.md
+++ b/astro-site/src/content/docs/datasets/cmidss.mdx
@@ -1,4 +1,7 @@
-# CMIDSS Dataset
+---
+title: "CMIDSS Dataset"
+description: "This dataset comes from the Child Mind Institute - Detect Sleep States (CMIDSS) Kaggle competition. The dataset comprises 300 subjects with over 500 multi-day…"
+---
## Overview
@@ -16,13 +19,13 @@ The CMIDSS dataset is available for non-commercial use under [Attribution-NonCom
## Task integration
-Use CMIDSS for [sleep detection](../tasks/detect.md). Its onset/wakeup annotations do not provide sleep-stage or apnea labels. See the [detection label policy](../detection-label-policy.md) for the derived target used by the experimental recipe.
+Use CMIDSS for [sleep detection](/sleepkit/tasks/detect/). Its onset/wakeup annotations do not provide sleep-stage or apnea labels. See the [detection label policy](/sleepkit/detection-label-policy/) for the derived target used by the experimental recipe.
## Installation
The dataset adapter has two download paths. `download_raw_dataset()` retrieves the competition data through the Kaggle client and converts subject recordings to HDF5. Configure the Kaggle client and obtain competition access before running:
-```python
+```python title="Python example"
import sleepkit as sk
dataset = sk.DatasetFactory.get("cmidss")(path="./datasets/cmidss")
diff --git a/astro-site/src/content/docs/datasets/index.mdx b/astro-site/src/content/docs/datasets/index.mdx
new file mode 100644
index 0000000..6788e23
--- /dev/null
+++ b/astro-site/src/content/docs/datasets/index.mdx
@@ -0,0 +1,34 @@
+---
+title: "Datasets"
+description: "sleepKIT provides support for a number of datasets to facilitate training the sleep-monitoring tasks. Most of the datasets are readily available and can be…"
+---
+
+sleepKIT provides support for a number of datasets to facilitate training the __sleep-monitoring tasks__. Most of the datasets are readily available and can be downloaded and used for training and evaluation. The datasets inherit from [Dataset](/sleepkit/api/sleepkit/datasets/dataset) and can be accessed either directly or through the factory singleton [`sk.DatasetFactory`](#dataset-factory).
+
+## Available Datasets
+
+Below is a list of the currently available datasets in sleepKIT. Please make sure to review each dataset's license for terms and limitations.
+
+* **[MESA](/sleepkit/datasets/mesa/)**: A longitudinal investigation of factors associated with the development of subclinical cardiovascular disease and the progression of subclinical to clinical cardiovascular disease in 6,814 black, white, Hispanic, and Chinese
+
+* **[CMIDSS](/sleepkit/datasets/cmidss/)**: The Child Mind Institute - Detect Sleep States (CMIDSS) dataset comprises 300 subjects with over 500 multi-day recordings of wrist-worn accelerometer data annotated with two event types: onset, the beginning of sleep, and wakeup, the end of sleep.
+
+* **[YSYW](/sleepkit/datasets/ysyw/)**: A total of 1,983 PSG recordings were provided by the Massachusetts General Hospital’s (MGH) Sleep Lab in the Sleep Division together with the Computational Clinical Neurophysiology Laboratory, and the Clinical Data Ani- mation Center.
+
+* **[STAGES](/sleepkit/datasets/stages/)**: The Stanford Technology Analytics and Genomics in Sleep (STAGES) study is a prospective cross-sectional, multi-site study involving 20 data collection sites from six centers including Stanford University, Bogan Sleep Consulting, Geisinger Health, Mayo Clinic, MedSleep, and St. Luke's Hospital.
+
+* **[Bring-Your-Own-Data](/sleepkit/datasets/byod/)**: Add new datasets to sleepKIT by providing your own data. Subclass `Dataset` and register it with the `sk.DatasetFactory`.
+
+---
+
+## Dataset Factory
+
+The dataset factory, `sk.DatasetFactory`, provides a convenient way to access the datasets. The factory is a thread-safe singleton class that provides a single point of access to the datasets via the datasets' slug names. The benefit of using the factory is it allows registering new additional datasets that can then be leveraged by existing and new tasks.
+
+The dataset factory provides the following methods:
+
+* **sk.DatasetFactory.register**: Register a custom dataset
+* **sk.DatasetFactory.unregister**: Unregister a custom dataset
+* **sk.DatasetFactory.has**: Check if a dataset is registered
+* **sk.DatasetFactory.get**: Get a dataset
+* **sk.DatasetFactory.list**: List all available datasets
diff --git a/docs/datasets/mesa.md b/astro-site/src/content/docs/datasets/mesa.mdx
similarity index 86%
rename from docs/datasets/mesa.md
rename to astro-site/src/content/docs/datasets/mesa.mdx
index 0a3b112..63fe1a3 100644
--- a/docs/datasets/mesa.md
+++ b/astro-site/src/content/docs/datasets/mesa.mdx
@@ -1,4 +1,7 @@
-# MESA Dataset
+---
+title: "MESA Dataset"
+description: "Multi-Ethnic Study of Atherosclerosis (MESA) is an NHLBI-sponsored 6-center collaborative longitudinal investigation of factors associated with the development…"
+---
## Overview
@@ -16,15 +19,15 @@ The MESA dataset is available for non-commercial and commercial use.
## Supported Tasks
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
+* [Sleep Detect](/sleepkit/tasks/detect/)
+* [Sleep Stage](/sleepkit/tasks/stage/)
+* [Sleep Apnea](/sleepkit/tasks/apnea/)
## Installation
The MESA dataset is available for download from the [NSRR website](https://sleepdata.org/datasets/mesa). Please note, a user account and permission to access the dataset is required. Once granted permission, the dataset can be downloaded using the `sleepkit` package. Please note, the `NSRR_TOKEN` environment variable must be set to the user's token prior to downloading. The dataset can be downloaded using the following command:
-```bash
+```bash title="Terminal"
export NSRR_TOKEN="INSERT_TOKEN_HERE"
diff --git a/docs/datasets/stages.md b/astro-site/src/content/docs/datasets/stages.mdx
similarity index 89%
rename from docs/datasets/stages.md
rename to astro-site/src/content/docs/datasets/stages.mdx
index 577b5c9..a90a6b7 100644
--- a/docs/datasets/stages.md
+++ b/astro-site/src/content/docs/datasets/stages.mdx
@@ -1,4 +1,7 @@
-# STAGES Dataset
+---
+title: "STAGES Dataset"
+description: "The Stanford Technology Analytics and Genomics in Sleep (STAGES) study is a prospective cross-sectional, multi-site study involving 20 data collection sites…"
+---
## Overview
@@ -29,15 +32,15 @@ The STAGES dataset is available for non-commercial and commercial use.
## Supported Tasks
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
+* [Sleep Detect](/sleepkit/tasks/detect/)
+* [Sleep Stage](/sleepkit/tasks/stage/)
+* [Sleep Apnea](/sleepkit/tasks/apnea/)
## Installation
The STAGES dataset is available for download from the [NSRR website](https://sleepdata.org/datasets/stages). Please note, a user account and permission to access the dataset is required. Once granted permission, the dataset can be downloaded using the `sleepkit` package. Please note, the `NSRR_TOKEN` environment variable must be set to the user's token prior to downloading. The dataset can be downloaded using the following command:
-```bash
+```bash title="Terminal"
export NSRR_TOKEN="INSERT_TOKEN_HERE"
diff --git a/docs/datasets/synthetic.md b/astro-site/src/content/docs/datasets/synthetic.mdx
similarity index 50%
rename from docs/datasets/synthetic.md
rename to astro-site/src/content/docs/datasets/synthetic.mdx
index 2ce9262..8a0cbde 100644
--- a/docs/datasets/synthetic.md
+++ b/astro-site/src/content/docs/datasets/synthetic.mdx
@@ -1,4 +1,7 @@
-# Synthetic Data
+---
+title: "Synthetic Data"
+description: "By leveraging physioKIT, we are able to generate synthetic data for a variety of physiological signals, including ECG, PPG, and respiration. In addition to the…"
+---
### Overview
@@ -6,7 +9,6 @@ By leveraging [physioKIT](https://ambiqai.github.io/physiokit/), we are able to
Please visit [physioKIT](https://ambiqai.github.io/physiokit/) for more details.
-
## Funding
NA
@@ -17,31 +19,29 @@ The tool is available under BSD-3-Clause License.
## Integration
-
-
## Usage
-!!! Example Python
+**Python**
- ```py linenums="1"
- import physiokit as pk
+```py title="Python example" linenums="1"
+import physiokit as pk
- heart_rate = 64 # BPM
- sample_rate = 1000 # Hz
- signal_length = 10*sample_rate # 10 seconds
+heart_rate = 64 # BPM
+sample_rate = 1000 # Hz
+signal_length = 10*sample_rate # 10 seconds
- # Generate NSR synthetic ECG signal
- ecg, segs, fids = pk.ecg.synthesize(
- signal_length=signal_length,
- sample_rate=sample_rate,
- heart_rate=heart_rate,
- leads=1,
- preset=pk.ecg.EcgPreset.NSR,
- p_multiplier=1.5,
- t_multiplier=1.2,
- noise_multiplier=0.2
- )
+# Generate NSR synthetic ECG signal
+ecg, segs, fids = pk.ecg.synthesize(
+ signal_length=signal_length,
+ sample_rate=sample_rate,
+ heart_rate=heart_rate,
+ leads=1,
+ preset=pk.ecg.EcgPreset.NSR,
+ p_multiplier=1.5,
+ t_multiplier=1.2,
+ noise_multiplier=0.2
+)
- ```
+```
-Synthetic signal generation is a standalone preprocessing tool, not a registered sleepKIT dataset. To use generated signals in a task, provide a [custom dataset adapter](byod.md) and matching feature extraction.
+Synthetic signal generation is a standalone preprocessing tool, not a registered sleepKIT dataset. To use generated signals in a task, provide a [custom dataset adapter](/sleepkit/datasets/byod/) and matching feature extraction.
diff --git a/docs/datasets/ysyw.md b/astro-site/src/content/docs/datasets/ysyw.mdx
similarity index 73%
rename from docs/datasets/ysyw.md
rename to astro-site/src/content/docs/datasets/ysyw.mdx
index a54d4e2..96697db 100644
--- a/docs/datasets/ysyw.md
+++ b/astro-site/src/content/docs/datasets/ysyw.mdx
@@ -1,4 +1,7 @@
-# YSYW Dataset
+---
+title: "YSYW Dataset"
+description: "A total of 1,983 PSG recordings were provided by the Massachusetts General Hospital’s (MGH) Sleep Lab in the Sleep Division together with the Computational…"
+---
## Overview
@@ -14,9 +17,8 @@ Funding was from the National Institutes of Health, grant R01-GM104987. We are a
The YSYW dataset is available commercial use under [Open Data Commons Attribution License](https://physionet.org/content/challenge-2018/view-license/1.0.0/).
-
## Supported Tasks
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
+* [Sleep Detect](/sleepkit/tasks/detect/)
+* [Sleep Stage](/sleepkit/tasks/stage/)
+* [Sleep Apnea](/sleepkit/tasks/apnea/)
diff --git a/docs/detection-annotated-dataset.md b/astro-site/src/content/docs/detection-annotated-dataset.mdx
similarity index 88%
rename from docs/detection-annotated-dataset.md
rename to astro-site/src/content/docs/detection-annotated-dataset.mdx
index c23fbb6..a3a5c60 100644
--- a/docs/detection-annotated-dataset.md
+++ b/astro-site/src/content/docs/detection-annotated-dataset.mdx
@@ -1,4 +1,7 @@
-# Training with the annotated-period target
+---
+title: "Training with the annotated-period target"
+description: "AnnotatedDataset composes the verified source, raw events, candidate policy, and frozen assignment as a read-only source adapter. It reconstructs the verified…"
+---
`AnnotatedDataset` composes the verified source, raw events, candidate policy, and
frozen assignment as a read-only source adapter. It reconstructs the verified UTC
@@ -6,7 +9,7 @@ clock and builds target arrays in memory. It neither loads historical
`sleep_stages` values nor rewrites original files. This keeps target derivation
versioned without duplicating the entire sensor dataset.
-```python
+```python title="Python example"
from sleepkit.recipes.detection.target_dataset import AnnotatedDataset
from sleepkit.recipes.detection.recipe import Config, run_membership
@@ -67,7 +70,7 @@ Every membership run retains these local files outside the public bundle:
Index creation checks every eligible target against the evaluated target sequence,
not only the total length. The index also rejects a different frozen context length.
-Its coordinates support the [common-index comparison](detection-comparison.md)
+Its coordinates support the [common-index comparison](/sleepkit/detection-comparison/)
with historical model outputs. Test prediction collection
currently retains batches in memory before writing NPZ; index writing streams by
subject. This is an offline recipe, not a causal streaming detector.
@@ -89,8 +92,8 @@ historical labels, train-only fitted state, Keras/TFLite parity, exact scored ta
metric reproduction from saved predictions, unlabeled inference, and artifact privacy.
The legacy training/inference tests remain supported.
-The [first declared experiment](detection-first-experiment.md) is complete, with
+The [first declared experiment](/sleepkit/detection-first-experiment/) is complete, with
pooled and per-series membership metrics and sampled real-input Keras/TFLite parity.
-Its read-only report can be reproduced from saved scoring evidence. The [common scoring intersection](detection-comparison.md) and
-[INT8 conversion](detection-int8.md) are documented separately. Historical training exposure, task acceptance thresholds, artifact
+Its read-only report can be reproduced from saved scoring evidence. The [common scoring intersection](/sleepkit/detection-comparison/) and
+[INT8 conversion](/sleepkit/detection-int8/) are documented separately. Historical training exposure, task acceptance thresholds, artifact
licensing and hardware validation remain separate questions.
diff --git a/docs/detection-comparison.md b/astro-site/src/content/docs/detection-comparison.mdx
similarity index 94%
rename from docs/detection-comparison.md
rename to astro-site/src/content/docs/detection-comparison.mdx
index 6e718fc..f7fd451 100644
--- a/docs/detection-comparison.md
+++ b/astro-site/src/content/docs/detection-comparison.mdx
@@ -1,12 +1,15 @@
-# Detection diagnostics and historical comparison
+---
+title: "Detection diagnostics and historical comparison"
+description: "The first experiment now has read-only error diagnostics and a separate, explicit SD-2 comparison recipe. These steps consume the same saved run evidence. They…"
+---
-The [first experiment](detection-first-experiment.md) now has read-only error
+The [first experiment](/sleepkit/detection-first-experiment/) now has read-only error
diagnostics and a separate, explicit SD-2 comparison recipe. These steps consume
the same saved run evidence. They do not retrain a model or tune a threshold.
## Error diagnostics
-```sh
+```sh title="Terminal"
python -m sleepkit.recipes.detection.error_analysis \
--run /path/to/membership-run \
--output /path/to/new-error-analysis.json
@@ -122,7 +125,7 @@ source, and output hashes also matched. No material finding remained.
## Compose the comparison in Python
-```python
+```python title="Python example"
from sleepkit.recipes.detection.comparison import compare
from sleepkit.recipes.detection.target_dataset import AnnotatedDataset
@@ -165,5 +168,5 @@ both flattened prediction arrays. These files contain identifiers and remain
outside public bundles. Existing output directories are refused. Failed runs
retain partial evidence without a completed comparison report.
-The next [fixed int8 conversion](detection-int8.md) preserves the new model's
+The next [fixed int8 conversion](/sleepkit/detection-int8/) preserves the new model's
preprocessing and measures quantization separately from this historical comparison.
diff --git a/docs/detection-evaluation-protocol.md b/astro-site/src/content/docs/detection-evaluation-protocol.mdx
similarity index 91%
rename from docs/detection-evaluation-protocol.md
rename to astro-site/src/content/docs/detection-evaluation-protocol.mdx
index be66bf7..369cf35 100644
--- a/docs/detection-evaluation-protocol.md
+++ b/astro-site/src/content/docs/detection-evaluation-protocol.mdx
@@ -1,7 +1,9 @@
-# Detection evaluation checkpoint
-
-This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](detection-annotated-dataset.md) and [comparison report](detection-comparison.md). The checkpoint discussion below records the decisions leading to that workflow.
+---
+title: "Detection evaluation checkpoint"
+description: "This page preserves a historical evaluation checkpoint. For the implemented workflow, see the annotated dataset adapter and comparison report. The checkpoint…"
+---
+This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](/sleepkit/detection-annotated-dataset/) and [comparison report](/sleepkit/detection-comparison/). The checkpoint discussion below records the decisions leading to that workflow.
The pipeline and artifact contracts are implemented. The next question is whether
a comparison is valid, before asking which model scores better. This checkpoint
@@ -12,7 +14,7 @@ It does not change source labels, select a split, or establish benchmark results
From the checkout, in an environment with NumPy and h5py:
-```sh
+```sh title="Terminal"
python -m sleepkit.recipes.detection.audit \
--data /path/to/cmidss \
--events /path/to/cmidss/train_events.csv \
@@ -146,21 +148,20 @@ At this checkpoint, raw-series alignment and annotation-policy review were
the next steps; their completed records are linked below. Historical model exposure and model licensing remain unresolved. No model
publication is authorized by producing an audit report.
-The [event-supported label policy](detection-label-policy.md) records the
+The [event-supported label policy](/sleepkit/detection-label-policy/) records the
subsequent review and adopted target. It does not overwrite the audit output.
-The [raw-source verification](detection-source-alignment.md) now confirms step/index,
+The [raw-source verification](/sleepkit/detection-source-alignment/) now confirms step/index,
UTC cadence, and channel alignment for the audited local snapshot. Its 44 local-clock
jumps coincide with timezone-offset changes. This supplies source-alignment evidence;
annotation semantics and historical training exposure remain separate open questions.
-
## Current implementation status
The audit, raw alignment, independent-clock path, candidate policy, and target-aware
-adapter are merged. The [frozen assignment and target contract](detection-frozen-split.md)
+adapter are merged. The [frozen assignment and target contract](/sleepkit/detection-frozen-split/)
record the recovered primary annotation evidence and seed-zero evaluation cohort.
-The [first experiment](detection-first-experiment.md) and
-[diagnostics/common-index comparison](detection-comparison.md) now have local
+The [first experiment](/sleepkit/detection-first-experiment/) and
+[diagnostics/common-index comparison](/sleepkit/detection-comparison/) now have local
results. Historical model exposure and artifact licensing remain unresolved;
the comparison is descriptive rather than a verified historical held-out benchmark.
diff --git a/docs/detection-first-experiment.md b/astro-site/src/content/docs/detection-first-experiment.mdx
similarity index 93%
rename from docs/detection-first-experiment.md
rename to astro-site/src/content/docs/detection-first-experiment.mdx
index 3bb5190..58cec83 100644
--- a/docs/detection-first-experiment.md
+++ b/astro-site/src/content/docs/detection-first-experiment.mdx
@@ -1,4 +1,7 @@
-# First frozen-cohort membership experiment
+---
+title: "First frozen-cohort membership experiment"
+description: "The first new detection recipe run completed on 2026-09-20. Its final Keras model achieved 95.7657% accuracy and 0.955611 macro-F1 on the frozen test set. This…"
+---
The first new detection recipe run completed on 2026-09-20. Its final Keras model
achieved **95.7657% accuracy and 0.955611 macro-F1** on the frozen test set.
@@ -25,7 +28,7 @@ The frozen series assignment and retained contexts were:
The split file SHA-256 is
`08c2ac221b3212b5589d29f623015994da8c6fd104708879b40bcb4db60306e7`.
-The [annotated dataset adapter](detection-annotated-dataset.md) reconstructs targets
+The [annotated dataset adapter](/sleepkit/detection-annotated-dataset/) reconstructs targets
from verified events and clocks; it ignores historical `sleep_stages` arrays.
Preprocessing v3 uses five features, 60-second windows, and a 30-second stride.
Normalization fits all valid frames from the 193 training series, including
@@ -96,7 +99,7 @@ For a completed membership run, the read-only evaluation helper needs NumPy and
the local scoring evidence, but does not load TensorFlow, source recordings, or
the model:
-```sh
+```sh title="Terminal"
python -m sleepkit.recipes.detection.evaluation \
--run /path/to/run \
--output /path/to/new-evaluation.json
@@ -123,7 +126,7 @@ committed with this report.
## Next evidence gates
-The [error diagnostics and historical comparison](detection-comparison.md) now
+The [error diagnostics and historical comparison](/sleepkit/detection-comparison/) now
report series, context-position, and observed-transition errors and compare both
pipelines on an exact common scoring intersection. Any changes informed by these
test reports must be declared; the current test set is no longer untouched for
diff --git a/docs/detection-frozen-split.md b/astro-site/src/content/docs/detection-frozen-split.mdx
similarity index 91%
rename from docs/detection-frozen-split.md
rename to astro-site/src/content/docs/detection-frozen-split.mdx
index ff6d180..5eaf998 100644
--- a/docs/detection-frozen-split.md
+++ b/astro-site/src/content/docs/detection-frozen-split.mdx
@@ -1,9 +1,12 @@
-# Frozen evaluation assignment and target
+---
+title: "Frozen evaluation assignment and target"
+description: "The reviewed audit/clock/candidate stack (#22–#25) is integrated into main. This checkpoint defines the derived target and freezes a reproducible split. It is…"
+---
The reviewed audit/clock/candidate stack (#22–#25) is integrated into `main`.
This checkpoint defines the derived target and freezes a reproducible split. It
is assignment-only: running the existing recipe with `split.json` still reads
-historical HDF5 labels. The separate [annotated dataset recipe](detection-annotated-dataset.md) applies the
+historical HDF5 labels. The separate [annotated dataset recipe](/sleepkit/detection-annotated-dataset/) applies the
derived target and writes exact scoring evidence.
## Target: annotated nightly-period membership
@@ -30,7 +33,7 @@ model output names remain unchanged; future dataset/model artifacts must carry
Source retrieval (public, no credentials):
-```sh
+```sh title="Terminal"
curl -s https://www.kaggle.com/api/i/competitions.PageService/ListPages \
-H 'Content-Type: application/json' --data '{"competitionId":53666}'
```
@@ -43,7 +46,7 @@ identity statement; no independent person-linkage audit was performed.
## Deterministic assignment
-```sh
+```sh title="Terminal"
uv run python -m sleepkit.recipes.detection.split \
--data /path/to/original-cmidss --coverage /path/to/candidate-coverage.json \
--output /path/to/new-frozen-split --seed 0
@@ -86,6 +89,6 @@ training exposure remains unknown, so this new split cannot certify that model
as held out. Preserve historical preprocessing and treat its results as descriptive
until exposure evidence exists.
-The [read-only target adapter](detection-annotated-dataset.md) now derives labels
+The [read-only target adapter](/sleepkit/detection-annotated-dataset/) now derives labels
in memory from verified events, retains unknown masks, uses this frozen assignment,
and persists exact scoring indices with target-specific artifact metadata.
diff --git a/docs/detection-golden.md b/astro-site/src/content/docs/detection-golden.mdx
similarity index 90%
rename from docs/detection-golden.md
rename to astro-site/src/content/docs/detection-golden.mdx
index 270d3c4..4d39b2d 100644
--- a/docs/detection-golden.md
+++ b/astro-site/src/content/docs/detection-golden.mdx
@@ -1,4 +1,7 @@
-# Detection golden baseline
+---
+title: "Detection golden baseline"
+description: "experiments/detection-golden.json defines a public reconstruction of the first annotated-period membership run. It records the exact recipe configuration,…"
+---
`experiments/detection-golden.json` defines a public reconstruction of the first
annotated-period membership run. It records the exact recipe configuration,
@@ -17,7 +20,7 @@ This is a reconstruction definition, not a universal runner or a release
manifest. The ordinary Python entry point validates the supplied local evidence
against the pinned aggregate hashes and then calls `run_membership`:
-```sh
+```sh title="Terminal"
python experiments/run_detection_golden.py \
--data /path/to/original-cmidss \
--events /path/to/train_events.csv \
@@ -40,7 +43,7 @@ definition and runner hash remain attached to that run.
Performance measurements are a separate concern; use the bounded ordinary-Python
profiler at `python -m sleepkit.recipes.detection.profile` with the same local
-dataset evidence; see the [profiling guide](detection-profiling.md). Its results
+dataset evidence; see the [profiling guide](/sleepkit/detection-profiling/). Its results
are not part of this golden quality reference.
The target is `sleepkit.annotated_period_membership/v1`: class 0 is
@@ -84,8 +87,8 @@ These are observed reference values from one recorded run. They are not
prospective acceptance thresholds or quality gates. Seeded execution is not a
bitwise reproducibility guarantee across environments, and a run from the current
checkout is expected to be a reconstruction rather than a byte-identical replay.
-The [first experiment report](detection-first-experiment.md) and
-[annotated target adapter](detection-annotated-dataset.md) provide the surrounding
+The [first experiment report](/sleepkit/detection-first-experiment/) and
+[annotated target adapter](/sleepkit/detection-annotated-dataset/) provide the surrounding
evidence and interpretation. Exposure of a separate historical SD-2 comparator to
this cohort remains unresolved; that question does not qualify this newly trained
frozen-split baseline.
@@ -94,6 +97,6 @@ The vectorized preparation revision advances only the current preprocessing
implementation pin. The original module hashes remain under `historical_run`, and
the original definition remains available at commit
`042c1eef5608db3bb842f29c6f12b768663f9026`. The
-[preparation equivalence report](detection-preparation-performance.md) binds the
+preparation equivalence report binds the
revised implementation to exact scalar-reference comparisons. Historical quality
metrics remain observations from the original five-epoch run.
diff --git a/docs/detection-int8.md b/astro-site/src/content/docs/detection-int8.mdx
similarity index 93%
rename from docs/detection-int8.md
rename to astro-site/src/content/docs/detection-int8.mdx
index 07ba35a..86fe6d6 100644
--- a/docs/detection-int8.md
+++ b/astro-site/src/content/docs/detection-int8.mdx
@@ -1,13 +1,16 @@
-# Fixed int8 conversion and release preparation
+---
+title: "Fixed int8 conversion and release preparation"
+description: "This step converts the first membership experiment without retraining or replacing its fitted preprocessing. It preserves the original float TFLite and Keras…"
+---
-This step converts the [first membership experiment](detection-first-experiment.md)
+This step converts the [first membership experiment](/sleepkit/detection-first-experiment/)
without retraining or replacing its fitted preprocessing. It preserves the original
float TFLite and Keras bytes and measures the quantized model on exactly the same
eligible test outputs.
## Run the Python recipe
-```python
+```python title="Python example"
from sleepkit.recipes.detection.quantization import quantize_run
# source is the same AnnotatedDataset used for the original run.
@@ -116,7 +119,7 @@ per model with bitwise-identical outputs. No material finding remained.
The existing raw-sensor entry point supports both bundled models:
-```python
+```python title="Python example"
from sleepkit.recipes.detection.inference import predict
integer = predict("int8-run/bundle", sensor_data, sample_time=utc_seconds)
@@ -142,11 +145,11 @@ The local experiment directory additionally retains the declaration, private
calibration evidence, per-series evaluation, and exact int8/float test arrays.
Staging refuses existing output directories and preserves the original run.
Once release rights and terms are established, use the generic
-[`stage-release` operation](huggingface-artifacts.md#stage-a-licensed-release-from-an-experiment)
+[`stage-release` operation](/sleepkit/huggingface-artifacts/#stage-a-licensed-release-from-an-experiment)
to add the selected license, public decision record and release card without
reconverting the models or replacing their validation evidence.
-```sh
+```sh title="Terminal"
python -m sleepkit.artifacts validate /path/to/int8-run/bundle \
--profile runnable --runtime
python -m sleepkit.artifacts publish /path/to/int8-run/bundle \
@@ -156,7 +159,7 @@ python -m sleepkit.artifacts publish /path/to/int8-run/bundle \
The second command is a local dry run. The repository name is a proposed dedicated
destination, not an existing deployment. Upload requires an explicitly chosen model
artifact license and the `--upload` option; source-code licensing is not assumed to
-cover model weights. The [licensing policy](model-licensing-policy.md) records
+cover model weights. The [licensing policy](/sleepkit/model-licensing-policy/) records
CC BY-NC-SA 4.0 without an Ambiq hardware restriction as the conservative candidate
for this CMIDSS model. Data-access, training-purpose and model-redistribution facts
still need to be recorded before release; choosing an NC label alone does not
diff --git a/docs/detection-label-policy.md b/astro-site/src/content/docs/detection-label-policy.mdx
similarity index 90%
rename from docs/detection-label-policy.md
rename to astro-site/src/content/docs/detection-label-policy.mdx
index be9fdb0..7ecb177 100644
--- a/docs/detection-label-policy.md
+++ b/astro-site/src/content/docs/detection-label-policy.mdx
@@ -1,7 +1,9 @@
-# Candidate event-supported label policy
-
-This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](detection-annotated-dataset.md) and [comparison report](detection-comparison.md). The checkpoint discussion below records the decisions leading to that workflow.
+---
+title: "Candidate event-supported label policy"
+description: "This page preserves a historical evaluation checkpoint. For the implemented workflow, see the annotated dataset adapter and comparison report. The checkpoint…"
+---
+This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](/sleepkit/detection-annotated-dataset/) and [comparison report](/sleepkit/detection-comparison/). The checkpoint discussion below records the decisions leading to that workflow.
Status: implemented candidate policy `sleepkit.event_candidates/v1`, separate from
the active training label policy. No existing HDF5 labels or historical model inputs are rewritten here.
@@ -66,7 +68,7 @@ available event timestamp directly with raw UTC at its source step (pair duratio
alone cannot detect an equal shift of both timestamps), and test a pure interval
builder that enforces consecutive integer night IDs and excludes incomplete or
conflicting intervening groups. The optional event-clock audit now implements the first check; see
-[independent sample clocks](detection-sample-clock.md). The pure interval builder and read-only coverage audit are now implemented.
+[independent sample clocks](/sleepkit/detection-sample-clock/). The pure interval builder and read-only coverage audit are now implemented.
Annotation-semantics review remains pending before these candidates become
evaluation ground truth.
@@ -77,13 +79,12 @@ sample clock. A source alignment report can establish that a particular snapshot
is continuous in UTC even when local clocks jump. That finding does not justify
accepting arbitrary one-hour jumps from other inputs.
-The [verified source adapter](detection-sample-clock.md) supplies an explicit UTC sample
+The [verified source adapter](/sleepkit/detection-sample-clock/) supplies an explicit UTC sample
clock alongside local TS. Validate cadence against that clock, use local TS only
for time-of-day features, and carry the clock contract through training and
unlabeled inference. Keep the existing strict check for inputs without sufficient
clock evidence. Do not add a global option that simply disables cadence checks.
-
## Pure builder and conflict rules
`candidate_labels.build_candidates(nights, sample_count, first_utc_seconds=...)`
@@ -108,7 +109,7 @@ nights. Shuffling rows and groups leaves the result unchanged.
## Read-only coverage audit
-```sh
+```sh title="Terminal"
uv run python -m sleepkit.recipes.detection.candidate_audit \
--data /path/to/original-cmidss --events /path/to/train_events.csv \
--alignment /path/to/passed-event-clock-alignment.json \
@@ -149,10 +150,10 @@ population, but this is not a model benchmark or evidence of label correctness.
The [official competition overview](https://www.kaggle.com/competitions/child-mind-institute-detect-sleep-states)
defines an event-detection task evaluated by average precision across timestamp
tolerances. This does not by itself establish dense clinical sleep/wake ground truth.
-The [retrieved annotation contract and frozen split](detection-frozen-split.md)
+The [retrieved annotation contract and frozen split](/sleepkit/detection-frozen-split/)
now support a derived annotated-period membership target, with explicit inside,
outside-supported-period, and unknown semantics. They do not support clinical
per-sample sleep/wake claims. The builder's historical candidate names remain
unchanged; future training artifacts must declare the adopted target explicitly.
-The [annotated dataset adapter and scoring index](detection-annotated-dataset.md)
+The [annotated dataset adapter and scoring index](/sleepkit/detection-annotated-dataset/)
now implement this contract without changing original labels.
diff --git a/docs/detection-profiling.md b/astro-site/src/content/docs/detection-profiling.mdx
similarity index 92%
rename from docs/detection-profiling.md
rename to astro-site/src/content/docs/detection-profiling.mdx
index 184b5ca..658126e 100644
--- a/docs/detection-profiling.md
+++ b/astro-site/src/content/docs/detection-profiling.mdx
@@ -1,4 +1,7 @@
-# Profiling the detection recipe
+---
+title: "Profiling the detection recipe"
+description: "The profiler measures the existing sleepKIT TensorFlow membership recipe before we change its loader. It calls the same feature preparation, normalization,…"
+---
The profiler measures the existing sleepKIT TensorFlow membership recipe before
we change its loader. It calls the same feature preparation, normalization,
@@ -8,9 +11,9 @@ validation/test predictions, choose a checkpoint, export a model or publish to H
Whole-cohort integrity checks still hash the frozen source files.
Run from a fresh process with the detection dependencies installed. Use the
-frozen dataset inputs described in [the golden experiment](detection-golden.md):
+frozen dataset inputs described in [the golden experiment](/sleepkit/detection-golden/):
-```sh
+```sh title="Terminal"
TF_NUM_INTRAOP_THREADS=2 TF_NUM_INTEROP_THREADS=1 OMP_NUM_THREADS=2 \
python -m sleepkit.recipes.detection.profile \
--data "$DATA" --events "$EVENTS" \
@@ -85,7 +88,7 @@ Keep prediction-quality reproduction separate from performance experiments.
## First CPU observation
-The [2026-09-20 evidence](evidence/membership-tcn-seed0-cpu-20260920/report.json)
+The [2026-09-20 evidence](/sleepkit/evidence/membership-tcn-seed0-cpu-20260920/report.json)
contains the declaration, environment and report for the frozen membership training
partition: 193 series, 14,857,307 valid normalization frames, 34,474 eligible
contexts, 1,078 batches, and ten contexts in the final batch. No held-out feature
@@ -116,4 +119,4 @@ do not establish a TensorFlow backend bottleneck. Candidate optimizations must
preserve the recorded feature/normalizer and sample contracts and be compared in
repeated, controlled runs before any improvement claim.
-The next measured change is [bounded vectorized feature preparation](detection-preparation-performance.md), with exact scalar-reference comparisons before reusing the existing feature contract.
+The next measured change is bounded vectorized feature preparation, with exact scalar-reference comparisons before reusing the existing feature contract.
diff --git a/docs/detection-recipe.md b/astro-site/src/content/docs/detection-recipe.mdx
similarity index 90%
rename from docs/detection-recipe.md
rename to astro-site/src/content/docs/detection-recipe.mdx
index d897de6..e13f669 100644
--- a/docs/detection-recipe.md
+++ b/astro-site/src/content/docs/detection-recipe.mdx
@@ -1,10 +1,13 @@
-# A detection pipeline written in Python
+---
+title: "A detection pipeline written in Python"
+description: "The new detection recipe is developed alongside the legacy task CLI. It reads CMIDSS sensor-channel HDF5 files and owns feature generation, normalization,…"
+---
The new detection recipe is developed alongside the legacy task CLI. It reads
CMIDSS sensor-channel HDF5 files and owns feature generation, normalization,
training, held-out evaluation, and artifact export. It uses ordinary functions,
a small config, a native Keras model, and the shared artifact package from
-[the HF publishing workflow](huggingface-artifacts.md).
+[the HF publishing workflow](/sleepkit/huggingface-artifacts/).
This is an experimental major-version building block. It does not reproduce the
historical SD-2-TCN-SM model. Global training-only normalization, invalid-data
@@ -19,7 +22,7 @@ CPU. TensorBoard is now an explicit dependency because legacy training uses its
callback and TF 2.21 no longer brings it in transitively. The original SleepKit
training dependencies remain installed; a full dependency split is later work.
-```sh
+```sh title="Terminal"
uv sync --extra detection
uv run --extra detection python -m sleepkit.recipes.detection smoke --output /tmp/detection-smoke
```
@@ -63,7 +66,7 @@ pair sleep events, or silently resample irregular signals.
Write a local subject split with three nonempty, disjoint partitions:
-```json
+```json title="JSON example"
{
"train": ["subject-a", "subject-b"],
"validation": ["subject-c"],
@@ -76,7 +79,7 @@ contributes to fitted normalization. For datasets with multiple recordings per
person, the adapter must group them under the same subject before creating splits;
this CMIDSS adapter treats each source series file as one subject.
-```sh
+```sh title="Terminal"
uv run --extra detection python -m sleepkit.recipes.detection train \
--data /path/to/cmidss --split /path/to/split.json \
--output /path/to/new-run --cache /path/to/local-feature-cache \
@@ -98,7 +101,7 @@ of each source timestamp: `mean(cos(2*pi*TS/86400))`. Encoding before averaging
keeps windows spanning midnight close to +1 rather than interpreting them as noon.
The v2 contract corrected the original time-of-day formula. The default v3
contract additionally validates continuity with an independent UTC sample clock;
-see [sample-clock alignment](detection-sample-clock.md).
+see [sample-clock alignment](/sleepkit/detection-sample-clock/).
Old v1 caches are bypassed, and v1 fitted states are rejected by this implementation.
Retrain and export a new bundle; do not pair v1 model weights or normalization with
v2 or v3 features. Historical baseline packaging and its original feature requirements
@@ -129,7 +132,7 @@ an incremental reader in a later adapter.
## Compose an experiment
-```python
+```python title="Python example"
from sleepkit.recipes.detection.recipe import Config, run
run(data_root, split_file, output_dir, Config(epochs=10),
@@ -145,7 +148,7 @@ This logits contract belongs to this recipe, not the generic artifact format.
Experiments can also import and call individual steps directly:
-```python
+```python title="Python example"
from sleepkit.recipes.detection.data import load_split, subject_features
from sleepkit.recipes.detection.preprocessing import Normalizer
@@ -182,7 +185,7 @@ fingerprints in the bundle verify a known local run, but cannot reconstruct its
private data. Metrics report the provided labels, not clinical accuracy. No task
acceptance threshold is implied by successful evaluation or runtime conformance.
-```sh
+```sh title="Terminal"
python -m sleepkit.artifacts validate /path/to/run/bundle --profile runnable --runtime
python -m sleepkit.recipes.detection predict \
--bundle /path/to/run/bundle --data /path/to/cmidss \
@@ -198,6 +201,6 @@ using the artifact API. License choice and publication are separate release work
## Validation scope
-The [first experiment](detection-first-experiment.md), [historical comparison](detection-comparison.md), and [INT8 conversion](detection-int8.md) document separate completed checkpoints and their evidence. Read their declared populations, target semantics and limitations before comparing results. These reports do not establish MCU validation or equivalence to a clinical sleep/wake task.
+The [first experiment](/sleepkit/detection-first-experiment/), [historical comparison](/sleepkit/detection-comparison/), and [INT8 conversion](/sleepkit/detection-int8/) document separate completed checkpoints and their evidence. Read their declared populations, target semantics and limitations before comparing results. These reports do not establish MCU validation or equivalence to a clinical sleep/wake task.
-The export path uses the native [Keras export API](https://keras.io/api/models/model_saving_apis/export/) and [TensorFlow-to-LiteRT conversion](https://developers.google.com/edge/litert/conversion/tensorflow/convert_tf). The [evaluation checkpoint](detection-evaluation-protocol.md) records the annotation audit and comparison requirements.
+The export path uses the native [Keras export API](https://keras.io/api/models/model_saving_apis/export/) and [TensorFlow-to-LiteRT conversion](https://developers.google.com/edge/litert/conversion/tensorflow/convert_tf). The [evaluation checkpoint](/sleepkit/detection-evaluation-protocol/) records the annotation audit and comparison requirements.
diff --git a/docs/detection-sample-clock.md b/astro-site/src/content/docs/detection-sample-clock.mdx
similarity index 92%
rename from docs/detection-sample-clock.md
rename to astro-site/src/content/docs/detection-sample-clock.mdx
index 6ecd7f5..8c45a6d 100644
--- a/docs/detection-sample-clock.md
+++ b/astro-site/src/content/docs/detection-sample-clock.mdx
@@ -1,4 +1,7 @@
-# Independent sample clocks
+---
+title: "Independent sample clocks"
+description: "Detection preprocessing v3 accepts local TS/ENMO/ZANGLE values plus an optional independent sampletime vector. It must contain signed int64 Unix seconds, align…"
+---
Detection preprocessing v3 accepts local TS/ENMO/ZANGLE values plus an optional
independent `sample_time` vector. It must contain signed int64 Unix seconds, align
@@ -6,7 +9,7 @@ one-to-one with source samples, and increase by exactly five seconds. UTC contro
sampling continuity; local TS still supplies the cyclic time-of-day feature. Without
an independent clock, the existing strict local-TS cadence check applies.
-```python
+```python title="Python example"
from sleepkit.recipes.detection.preprocessing import prepare
from sleepkit.recipes.detection.inference import predict
@@ -37,11 +40,11 @@ Use a fresh source-alignment report containing `first_utc_seconds` to build a se
clocked dataset. Only a successful report with matching source hashes can support
reconstruction of the regular UTC sequence. Older reports must be regenerated.
The clock materializer preserves historical labels; it does not implement the
-[candidate label policy](detection-label-policy.md).
+[candidate label policy](/sleepkit/detection-label-policy/).
## Event clock evidence
-```sh
+```sh title="Terminal"
uv run --extra source-audit python -m sleepkit.recipes.detection.alignment \
--data /path/to/cmidss --parquet /path/to/train_series.parquet \
--events /path/to/train_events.csv --output /path/to/new-alignment.json
@@ -55,7 +58,7 @@ requested audit; an entirely missing event set does not pass. The report binds t
events file hash and detects file changes during verification.
This verifies event timing, not sleep/wake semantics, independent-person grouping,
-or historical model training exposure. The [candidate interval builder and coverage audit](detection-label-policy.md) are
+or historical model training exposure. The [candidate interval builder and coverage audit](/sleepkit/detection-label-policy/) are
implemented separately. Annotation-protocol review remains a gate before benchmarking.
On the audited local snapshot, all 9,585 available event rows match raw UTC exactly;
@@ -66,7 +69,7 @@ These results apply only to the source hashes in the local report.
To copy explicitly selected subjects with verified clocks:
-```sh
+```sh title="Terminal"
uv run python -m sleepkit.recipes.detection.clock_source \
--data /path/to/cmidss --alignment /path/to/new-alignment.json \
--output /path/to/new-clocked-source --subjects subject_a subject_b
diff --git a/docs/detection-source-alignment.md b/astro-site/src/content/docs/detection-source-alignment.mdx
similarity index 87%
rename from docs/detection-source-alignment.md
rename to astro-site/src/content/docs/detection-source-alignment.mdx
index a5336aa..cabac69 100644
--- a/docs/detection-source-alignment.md
+++ b/astro-site/src/content/docs/detection-source-alignment.mdx
@@ -1,10 +1,13 @@
-# Raw-source alignment verification
+---
+title: "Raw-source alignment verification"
+description: "This check establishes whether the legacy HDF5 sensor rows match the raw Parquet series, independently of local time-of-day changes. It is separate from…"
+---
This check establishes whether the legacy HDF5 sensor rows match the raw Parquet
series, independently of local time-of-day changes. It is separate from annotation
coverage, person identity, and model evaluation.
-```sh
+```sh title="Terminal"
uv sync --extra detection --extra source-audit
uv run --extra source-audit python -m sleepkit.recipes.detection.alignment \
--data /path/to/cmidss --parquet /path/to/cmidss/train_series.parquet \
@@ -48,13 +51,13 @@ person, or that historical model training excluded any particular subject.
## Reader change supported by this evidence
The legacy detector path validates cadence using local TS and rejects these 44 files.
-The [independent sample-clock adapter](detection-sample-clock.md) now preserves an explicit UTC clock alongside
+The [independent sample-clock adapter](/sleepkit/detection-sample-clock/) now preserves an explicit UTC clock alongside
local TS, validates continuity against it, and uses local TS only for the time-of-day
feature. This contract carries through caching, training, and unlabeled inference.
Inputs without independent clock evidence retain the strict local-TS check.
-The [event-supported label policy](detection-label-policy.md) records the adopted
-derived annotated-period membership target. The [dataset adapter](detection-annotated-dataset.md)
+The [event-supported label policy](/sleepkit/detection-label-policy/) records the adopted
+derived annotated-period membership target. The [dataset adapter](/sleepkit/detection-annotated-dataset/)
implements that target without overwriting source labels.
## Parquet dependency compatibility
diff --git a/docs/features/byofs.md b/astro-site/src/content/docs/features/byofs.mdx
similarity index 82%
rename from docs/features/byofs.md
rename to astro-site/src/content/docs/features/byofs.mdx
index cae028a..b638491 100644
--- a/docs/features/byofs.md
+++ b/astro-site/src/content/docs/features/byofs.mdx
@@ -1,4 +1,7 @@
-# Bring-Your-Own-Features (BYOFS)
+---
+title: "Bring-Your-Own-Features (BYOFS)"
+description: "The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to sleepKIT to be used with built-in or custom tasks."
+---
The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to sleepKIT to be used with built-in or custom tasks.
@@ -6,7 +9,7 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
1. **Create a Feature Set**: Define a new feature set class that subclasses `sk.FeatureSet` and implements the feature contract. The following is a skeleton: implement the writer before calling it.
- ```py linenums="1"
+ ```py title="Python example" linenums="1"
import sleepkit as sk
class CustomFeatureSet(sk.FeatureSet):
@@ -25,14 +28,14 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
2. **Register the Feature Set**: Register the new feature set with the `sk.FeatureFactory` by calling the `register` method. This method takes the feature set name and the feature set class as arguments.
- ```py linenums="1"
+ ```py title="Python example" linenums="1"
import sleepkit as sk
sk.FeatureFactory.register(CustomFeatureSet.name(), CustomFeatureSet)
```
3. **Use the Feature Set**: The new feature set can now be used to generate feature sets.
- ```py linenums="1"
+ ```py title="Python example" linenums="1"
import sleepkit as sk
from pathlib import Path
diff --git a/docs/features/fs_c_ear_9.md b/astro-site/src/content/docs/features/fs_c_ear_9.mdx
similarity index 77%
rename from docs/features/fs_c_ear_9.md
rename to astro-site/src/content/docs/features/fs_c_ear_9.mdx
index 4e53777..e109f1e 100644
--- a/docs/features/fs_c_ear_9.md
+++ b/astro-site/src/content/docs/features/fs_c_ear_9.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-C-EAR-9
+---
+title: "Feature Set: FS-C-EAR-9"
+description: "This feature set is targeted for sleep stage classification based on sensor data available from chest location. The feature set computes heart rate (HR), heart…"
+---
## Overview
@@ -14,7 +17,7 @@ The target location for this feature set is the __chest__. From this location, t
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset does not directly provide accelerometer data from the chest. However, the dataset does provide respiratory signals (RIP) captured from both chest and abdomen. In place of accelerometer data, we use filtered chest respiratory signals as a proxy for body movement features.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset does not directly provide accelerometer data from the chest. However, the dataset does provide respiratory signals (RIP) captured from both chest and abdomen. In place of accelerometer data, we use filtered chest respiratory signals as a proxy for body movement features.
## Features
@@ -32,7 +35,6 @@ This feature set includes the following 9 features:
| rsp_bpm | Mean respiration rate derived from the respiratory signal | RSP |
| hrv_qos | Quality of signal derived from HRV | ECG |
-
## Output
The feature set is stored as HDF5 files (`.h5`) with one file per subject with path: `{save_path}/{dataset}/{subject_id}.h5`. Each HDF5 file includes the following entries:
diff --git a/docs/features/fs_h_e_10.md b/astro-site/src/content/docs/features/fs_h_e_10.mdx
similarity index 83%
rename from docs/features/fs_h_e_10.md
rename to astro-site/src/content/docs/features/fs_h_e_10.mdx
index 455193c..ff85971 100644
--- a/docs/features/fs_h_e_10.md
+++ b/astro-site/src/content/docs/features/fs_h_e_10.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-H-E-10
+---
+title: "Feature Set: FS-H-E-10"
+description: "This feature set is targeted for sleep stage classification based on single pair of EEG and EOG sensor data collected on head location. The feature set…"
+---
## Overview
@@ -13,7 +16,7 @@ The target location for this feature set is the __head__. From this location, th
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset provides EEG, EOG, and EMG data from the head location. The dataset also provides sleep stage labels.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset provides EEG, EOG, and EMG data from the head location. The dataset also provides sleep stage labels.
## Features
diff --git a/docs/features/fs_w_a_5.md b/astro-site/src/content/docs/features/fs_w_a_5.mdx
similarity index 78%
rename from docs/features/fs_w_a_5.md
rename to astro-site/src/content/docs/features/fs_w_a_5.mdx
index 9d6a48e..7d5ebda 100644
--- a/docs/features/fs_w_a_5.md
+++ b/astro-site/src/content/docs/features/fs_w_a_5.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-W-A-5
+---
+title: "Feature Set: FS-W-A-5"
+description: "This feature set is targeted towards actigraphy style sleep detection using only IMU based sensor data available from wrist location. The feature set computes…"
+---
## Overview
@@ -12,7 +15,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Dataset Support
-- **[CMIDSS](../datasets/cmidss.md)**: This dataset provides pre-computed movement and z-angle data from the wrist location every 5 seconds.
+- **[CMIDSS](/sleepkit/datasets/cmidss/)**: This dataset provides pre-computed movement and z-angle data from the wrist location every 5 seconds.
## Features
@@ -26,7 +29,6 @@ This feature set includes the following 5 features:
| angle_mu | Mean z-angle | IMU |
| angle_std | Standard deviation of z-angle | IMU |
-
## Output
The feature set is stored as HDF5 files (`.h5`) with one file per subject with path: `{save_path}/{dataset}/{subject_id}.h5`. Each HDF5 file includes the following entries:
diff --git a/docs/features/fs_w_p_5.md b/astro-site/src/content/docs/features/fs_w_p_5.mdx
similarity index 78%
rename from docs/features/fs_w_p_5.md
rename to astro-site/src/content/docs/features/fs_w_p_5.mdx
index 898a203..eed6aaf 100644
--- a/docs/features/fs_w_p_5.md
+++ b/astro-site/src/content/docs/features/fs_w_p_5.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-W-P-5
+---
+title: "Feature Set: FS-W-P-5"
+description: "This feature set is targeted for sleep apnea classification based on sensor data available from wrist location. The generator computes various features over…"
+---
## Overview
@@ -12,7 +15,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset does not directly provide dual PPG, however, the dataset does provide SpO2 and single channel PPG which is sufficient.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset does not directly provide dual PPG, however, the dataset does provide SpO2 and single channel PPG which is sufficient.
## Features
diff --git a/docs/features/fs_w_pa_14.md b/astro-site/src/content/docs/features/fs_w_pa_14.mdx
similarity index 79%
rename from docs/features/fs_w_pa_14.md
rename to astro-site/src/content/docs/features/fs_w_pa_14.mdx
index af9a3e8..c5af344 100644
--- a/docs/features/fs_w_pa_14.md
+++ b/astro-site/src/content/docs/features/fs_w_pa_14.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-W-PA-14
+---
+title: "Feature Set: FS-W-PA-14"
+description: "This feature set is targeted for sleep stage classification based on sensor data available from wrist location. The feature set computes heart rate, heart rate…"
+---
## Overview
@@ -13,7 +16,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset does not directly provide dual PPG nor Accelerometer data from the wrist. However, the dataset does provide SpO2 and single channel PPG which is sufficient for PPG derived features. In place of Accelerometer data, we use leg movement as a proxy for arm movement features.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset does not directly provide dual PPG nor Accelerometer data from the wrist. However, the dataset does provide SpO2 and single channel PPG which is sufficient for PPG derived features. In place of Accelerometer data, we use leg movement as a proxy for arm movement features.
## Features
@@ -36,7 +39,6 @@ This feature set includes the following 14 features:
| spo2_qos | Quality of signal derived from SpO2 | PPG |
| hrv_qos | Quality of signal derived from HRV | PPG |
-
## Output
The feature set is stored as HDF5 files (`.h5`) with one file per subject with path: `{save_path}/{dataset}/{subject_id}.h5`. Each HDF5 file includes the following entries:
diff --git a/astro-site/src/content/docs/features/index.mdx b/astro-site/src/content/docs/features/index.mdx
new file mode 100644
index 0000000..bc6b658
--- /dev/null
+++ b/astro-site/src/content/docs/features/index.mdx
@@ -0,0 +1,173 @@
+---
+title: "Features"
+description: "sleepKIT includes a mini feature store to enable crafting rich feature sets to train and evaluate models. The store includes several built-in feature set…"
+---
+
+import ConfigExample from "../../../components/ConfigExample.astro";
+
+__sleepKIT__ includes a mini _feature store_ to enable crafting rich feature sets to train and evaluate models. The store includes several built-in feature set generators that can be invoked to create feature sets for a variety of use cases. Each feature set inherits from `sk.FeatureSet` and provides implementations for generating features from the dataset.
+
+The main method, `generate_subject_features` receives the target dataset name, subject id, and high-level `sk.TaskParams` which includes field `feature` which includes feature set specific parameters. The resulting data and labels are stored in HDF5 format that can then be used for training via `sk.H5Dataloader` class. Custom feature set generators can also be added to the feature store by subclassing `sk.FeatureSet` and registering the new generator with the feature store.
+
+
+
+```json title="features-index-1.json"
+{
+ "name": "sd-2-tcn-sm",
+ "job_dir": "./results/sd-2-tcn-sm",
+ "verbose": 2,
+
+ "datasets": [{
+ "name": "cmidss",
+ "params": {
+ "path": "./datasets/cmidss"
+ }
+ }],
+
+ "feature": {
+ "name": "FS-W-A-5",
+ "sampling_rate": 0.2,
+ "frame_size": 12,
+ "loader": "hdf5",
+ "feat_key": "features",
+ "label_key": "detect_labels",
+ "mask_key": "mask",
+ "feat_cols": null,
+ "save_path": "./datasets/store/fs-w-a-5-60",
+ "params": {}
+ },
+
+ "sampling_rate": 0.0083333,
+ "frame_size": 240,
+
+ "num_classes": 2,
+ "class_map": {
+ "0": 0,
+ "1": 1,
+ "2": 1,
+ "3": 1,
+ "4": 1,
+ "5": 1
+ },
+ "class_names": ["WAKE", "SLEEP"],
+
+ "samples_per_subject": 100,
+ "val_samples_per_subject": 100,
+ "test_samples_per_subject": 50,
+
+ "val_size": 4000,
+ "test_size": 2500,
+
+ "val_subjects": 0.20,
+ "batch_size": 128,
+ "buffer_size": 10000,
+ "epochs": 200,
+ "steps_per_epoch": 25,
+ "val_steps_per_epoch": 25,
+ "val_metric": "loss",
+ "lr_rate": 1e-3,
+ "lr_cycles": 1,
+ "label_smoothing": 0,
+
+ "test_metric": "f1",
+ "test_metric_threshold": 0.02,
+ "tflm_var_name": "sk_detect_flatbuffer",
+ "tflm_file": "sk_detect_flatbuffer.h",
+
+ "backend": "pc",
+ "display_report": true,
+
+ "quantization": {
+ "qat": false,
+ "mode": "INT8",
+ "io_type": "int8",
+ "concrete": true,
+ "debug": false
+ },
+
+ "model_file": "model.keras",
+ "use_logits": false,
+ "architecture": {
+ "name": "tcn",
+ "params": {
+ "input_kernel": [1, 5],
+ "input_norm": "batch",
+ "blocks": [
+ {"depth": 1, "branch": 1, "filters": 16, "kernel": [1, 5], "dilation": [1, 1], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"},
+ {"depth": 1, "branch": 1, "filters": 32, "kernel": [1, 5], "dilation": [1, 2], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"},
+ {"depth": 1, "branch": 1, "filters": 48, "kernel": [1, 5], "dilation": [1, 4], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"},
+ {"depth": 1, "branch": 1, "filters": 64, "kernel": [1, 5], "dilation": [1, 8], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"}
+ ],
+ "output_kernel": [1, 5],
+ "include_top": true,
+ "use_logits": true,
+ "model_name": "tcn"
+ }
+ }
+}
+```
+
+
+
+
+ +```mermaid +graph TD +A("`Load +configuration +__TaskParams__ +`") +B("`Load datasets +__DatasetFactory__ +`") +C("`Load feature +generator +__FeatureFactory__ +`") +D("`Generate +features +`") +E("`Save +features +`") + +A ==> B +B ==> C +C ==> D +D ==> E + +``` + +--- + +## Available Feature Sets + +- **[FS-W-PA-14](/sleepkit/features/fs_w_pa_14/)**:__14__ features derived from __PPG__ and __IMU__ on __wrist__ for __sleep stage__ classification. +- **[FS-C-EAR-9](/sleepkit/features/fs_c_ear_9/)**: __9__ features derived from __ECG__, __RSP__, and __IMU__ on __chest__ for __sleep stage__ classification. +- **[FS-W-A-5](/sleepkit/features/fs_w_a_5/)**: __5__ features derived from __IMU__ on __wrist__ for actigraphy style __sleep detection__. +- **[FS-H-E-10](/sleepkit/features/fs_h_e_10/)**: __10__ features derived from __ECG__ and __EOG__ on __head__ for __sleep stage__ classification. +- **[FS-W-P-5](/sleepkit/features/fs_w_p_5/)**: __5__ features derived from __PPG__ on __wrist__ for __sleep apnea__ classification. +- **[BYOFS](/sleepkit/features/byofs/)**: Bring-Your-Own-Feature-Set (BYOFS) to create custom feature sets. + +## Feature Factory + +The feature factory, `sk.FeatureFactory`, provides a convenient way to access the feature sets. The factory is a thread-safe singleton class that provides a single point of access to the features via the features' slug names. The benefit of using the factory is it allows registering new additional feature sets that can then be leveraged by existing and new tasks. + +The feature factory provides the following methods: + +* **sk.FeatureFactory.register**: Register a custom feature set +* **sk.FeatureFactory.unregister**: Unregister a custom feature set +* **sk.FeatureFactory.has**: Check if a feature set is registered +* **sk.FeatureFactory.get**: Get a feature set +* **sk.FeatureFactory.list**: List all available feature sets diff --git a/astro-site/src/content/docs/guides/index.mdx b/astro-site/src/content/docs/guides/index.mdx new file mode 100644 index 0000000..76072a0 --- /dev/null +++ b/astro-site/src/content/docs/guides/index.mdx @@ -0,0 +1,34 @@ +--- +title: "User guide" +description: "Build a sleepKIT workflow from datasets, feature extraction and model architectures. Use the guides below to configure each step, then follow a tutorial for a…" +--- + +Build a sleepKIT workflow from datasets, feature extraction and model architectures. Use the guides below to configure each step, then follow a tutorial for a complete experiment. + +## Run an experiment + +Start with a task configuration and work through the modes you need. + +Configure a run +Download data +Train +Evaluate +Export +Run a demo + +## Choose your components + +- **Datasets** provide recordings and labels for your task. Review each dataset's access requirements and terms. +- **Feature sets** transform recordings into inputs for training and evaluation. +- **Model architectures** define the network and its configurable parameters. + +Browse datasets +Explore feature sets +Choose an architecture + +## Tutorials and experiments + +Train a sleep-detection model from wrist IMU data in the saved notebook, or explore how feature and model choices affect sleep staging. + +Detection training notebook +Staging ablation study diff --git a/docs/guides/stage-ablation.md b/astro-site/src/content/docs/guides/stage-ablation.mdx similarity index 81% rename from docs/guides/stage-ablation.md rename to astro-site/src/content/docs/guides/stage-ablation.mdx index 2ffa5c9..a158186 100644 --- a/docs/guides/stage-ablation.md +++ b/astro-site/src/content/docs/guides/stage-ablation.mdx @@ -1,5 +1,7 @@ -# Sleep Staging Ablation Studies - +--- +title: "Sleep Staging Ablation Studies" +description: "In the following, we perform ablation studies to investigate the impact of different design choices on the performance of the model. All ablation studies are…" +--- ## Overview @@ -12,7 +14,7 @@ We first evaluate the impact of the temporal context- the number of time steps t A typical night sleep involves 4 or 5 sleep cycles each of which lasts around 90-120 minutes. By providing the model with nearly an entire cycle allows the model to learn the patterns associated with each stage. However, providing the model with more than one cycle does not provide additional benefit. This is likely due to the fact that the model is already able to learn the patterns associated with each stage within a single cycle.
');
- const fenced = '```text\n!!! Example\n{ width="540" }\n```';
- assert.equal(normalizeMarkdown(fenced), fenced);
-});
diff --git a/docs/datasets/byod.md b/astro-site/src/content/docs/datasets/byod.mdx
similarity index 87%
rename from docs/datasets/byod.md
rename to astro-site/src/content/docs/datasets/byod.mdx
index 0edc66e..0525a8c 100644
--- a/docs/datasets/byod.md
+++ b/astro-site/src/content/docs/datasets/byod.mdx
@@ -1,12 +1,15 @@
-# Bring-Your-Own-Dataset (BYOD)
+---
+title: "Bring-Your-Own-Dataset (BYOD)"
+description: "A custom dataset subclasses sk.Dataset, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal…"
+---
-A custom dataset subclasses `sk.Dataset`, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal signal schema: pair the adapter with a [custom feature set](../features/byofs.md).
+A custom dataset subclasses `sk.Dataset`, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal signal schema: pair the adapter with a [custom feature set](/sleepkit/features/byofs/).
## Define the adapter
This example reads an existing directory of subject `.npz` files with a `signal` array. It makes an explicit subject split and does not download or invent data.
-```python
+```python title="Python example"
from pathlib import Path
import random
import numpy as np
diff --git a/docs/datasets/cmidss.md b/astro-site/src/content/docs/datasets/cmidss.mdx
similarity index 80%
rename from docs/datasets/cmidss.md
rename to astro-site/src/content/docs/datasets/cmidss.mdx
index 41ff5d6..7c38c73 100644
--- a/docs/datasets/cmidss.md
+++ b/astro-site/src/content/docs/datasets/cmidss.mdx
@@ -1,4 +1,7 @@
-# CMIDSS Dataset
+---
+title: "CMIDSS Dataset"
+description: "This dataset comes from the Child Mind Institute - Detect Sleep States (CMIDSS) Kaggle competition. The dataset comprises 300 subjects with over 500 multi-day…"
+---
## Overview
@@ -16,13 +19,13 @@ The CMIDSS dataset is available for non-commercial use under [Attribution-NonCom
## Task integration
-Use CMIDSS for [sleep detection](../tasks/detect.md). Its onset/wakeup annotations do not provide sleep-stage or apnea labels. See the [detection label policy](../detection-label-policy.md) for the derived target used by the experimental recipe.
+Use CMIDSS for [sleep detection](/sleepkit/tasks/detect/). Its onset/wakeup annotations do not provide sleep-stage or apnea labels. See the [detection label policy](/sleepkit/detection-label-policy/) for the derived target used by the experimental recipe.
## Installation
The dataset adapter has two download paths. `download_raw_dataset()` retrieves the competition data through the Kaggle client and converts subject recordings to HDF5. Configure the Kaggle client and obtain competition access before running:
-```python
+```python title="Python example"
import sleepkit as sk
dataset = sk.DatasetFactory.get("cmidss")(path="./datasets/cmidss")
diff --git a/astro-site/src/content/docs/datasets/index.mdx b/astro-site/src/content/docs/datasets/index.mdx
new file mode 100644
index 0000000..6788e23
--- /dev/null
+++ b/astro-site/src/content/docs/datasets/index.mdx
@@ -0,0 +1,34 @@
+---
+title: "Datasets"
+description: "sleepKIT provides support for a number of datasets to facilitate training the sleep-monitoring tasks. Most of the datasets are readily available and can be…"
+---
+
+sleepKIT provides support for a number of datasets to facilitate training the __sleep-monitoring tasks__. Most of the datasets are readily available and can be downloaded and used for training and evaluation. The datasets inherit from [Dataset](/sleepkit/api/sleepkit/datasets/dataset) and can be accessed either directly or through the factory singleton [`sk.DatasetFactory`](#dataset-factory).
+
+## Available Datasets
+
+Below is a list of the currently available datasets in sleepKIT. Please make sure to review each dataset's license for terms and limitations.
+
+* **[MESA](/sleepkit/datasets/mesa/)**: A longitudinal investigation of factors associated with the development of subclinical cardiovascular disease and the progression of subclinical to clinical cardiovascular disease in 6,814 black, white, Hispanic, and Chinese
+
+* **[CMIDSS](/sleepkit/datasets/cmidss/)**: The Child Mind Institute - Detect Sleep States (CMIDSS) dataset comprises 300 subjects with over 500 multi-day recordings of wrist-worn accelerometer data annotated with two event types: onset, the beginning of sleep, and wakeup, the end of sleep.
+
+* **[YSYW](/sleepkit/datasets/ysyw/)**: A total of 1,983 PSG recordings were provided by the Massachusetts General Hospital’s (MGH) Sleep Lab in the Sleep Division together with the Computational Clinical Neurophysiology Laboratory, and the Clinical Data Ani- mation Center.
+
+* **[STAGES](/sleepkit/datasets/stages/)**: The Stanford Technology Analytics and Genomics in Sleep (STAGES) study is a prospective cross-sectional, multi-site study involving 20 data collection sites from six centers including Stanford University, Bogan Sleep Consulting, Geisinger Health, Mayo Clinic, MedSleep, and St. Luke's Hospital.
+
+* **[Bring-Your-Own-Data](/sleepkit/datasets/byod/)**: Add new datasets to sleepKIT by providing your own data. Subclass `Dataset` and register it with the `sk.DatasetFactory`.
+
+---
+
+## Dataset Factory
+
+The dataset factory, `sk.DatasetFactory`, provides a convenient way to access the datasets. The factory is a thread-safe singleton class that provides a single point of access to the datasets via the datasets' slug names. The benefit of using the factory is it allows registering new additional datasets that can then be leveraged by existing and new tasks.
+
+The dataset factory provides the following methods:
+
+* **sk.DatasetFactory.register**: Register a custom dataset
+* **sk.DatasetFactory.unregister**: Unregister a custom dataset
+* **sk.DatasetFactory.has**: Check if a dataset is registered
+* **sk.DatasetFactory.get**: Get a dataset
+* **sk.DatasetFactory.list**: List all available datasets
diff --git a/docs/datasets/mesa.md b/astro-site/src/content/docs/datasets/mesa.mdx
similarity index 86%
rename from docs/datasets/mesa.md
rename to astro-site/src/content/docs/datasets/mesa.mdx
index 0a3b112..63fe1a3 100644
--- a/docs/datasets/mesa.md
+++ b/astro-site/src/content/docs/datasets/mesa.mdx
@@ -1,4 +1,7 @@
-# MESA Dataset
+---
+title: "MESA Dataset"
+description: "Multi-Ethnic Study of Atherosclerosis (MESA) is an NHLBI-sponsored 6-center collaborative longitudinal investigation of factors associated with the development…"
+---
## Overview
@@ -16,15 +19,15 @@ The MESA dataset is available for non-commercial and commercial use.
## Supported Tasks
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
+* [Sleep Detect](/sleepkit/tasks/detect/)
+* [Sleep Stage](/sleepkit/tasks/stage/)
+* [Sleep Apnea](/sleepkit/tasks/apnea/)
## Installation
The MESA dataset is available for download from the [NSRR website](https://sleepdata.org/datasets/mesa). Please note, a user account and permission to access the dataset is required. Once granted permission, the dataset can be downloaded using the `sleepkit` package. Please note, the `NSRR_TOKEN` environment variable must be set to the user's token prior to downloading. The dataset can be downloaded using the following command:
-```bash
+```bash title="Terminal"
export NSRR_TOKEN="INSERT_TOKEN_HERE"
diff --git a/docs/datasets/stages.md b/astro-site/src/content/docs/datasets/stages.mdx
similarity index 89%
rename from docs/datasets/stages.md
rename to astro-site/src/content/docs/datasets/stages.mdx
index 577b5c9..a90a6b7 100644
--- a/docs/datasets/stages.md
+++ b/astro-site/src/content/docs/datasets/stages.mdx
@@ -1,4 +1,7 @@
-# STAGES Dataset
+---
+title: "STAGES Dataset"
+description: "The Stanford Technology Analytics and Genomics in Sleep (STAGES) study is a prospective cross-sectional, multi-site study involving 20 data collection sites…"
+---
## Overview
@@ -29,15 +32,15 @@ The STAGES dataset is available for non-commercial and commercial use.
## Supported Tasks
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
+* [Sleep Detect](/sleepkit/tasks/detect/)
+* [Sleep Stage](/sleepkit/tasks/stage/)
+* [Sleep Apnea](/sleepkit/tasks/apnea/)
## Installation
The STAGES dataset is available for download from the [NSRR website](https://sleepdata.org/datasets/stages). Please note, a user account and permission to access the dataset is required. Once granted permission, the dataset can be downloaded using the `sleepkit` package. Please note, the `NSRR_TOKEN` environment variable must be set to the user's token prior to downloading. The dataset can be downloaded using the following command:
-```bash
+```bash title="Terminal"
export NSRR_TOKEN="INSERT_TOKEN_HERE"
diff --git a/docs/datasets/synthetic.md b/astro-site/src/content/docs/datasets/synthetic.mdx
similarity index 50%
rename from docs/datasets/synthetic.md
rename to astro-site/src/content/docs/datasets/synthetic.mdx
index 2ce9262..8a0cbde 100644
--- a/docs/datasets/synthetic.md
+++ b/astro-site/src/content/docs/datasets/synthetic.mdx
@@ -1,4 +1,7 @@
-# Synthetic Data
+---
+title: "Synthetic Data"
+description: "By leveraging physioKIT, we are able to generate synthetic data for a variety of physiological signals, including ECG, PPG, and respiration. In addition to the…"
+---
### Overview
@@ -6,7 +9,6 @@ By leveraging [physioKIT](https://ambiqai.github.io/physiokit/), we are able to
Please visit [physioKIT](https://ambiqai.github.io/physiokit/) for more details.
-
## Funding
NA
@@ -17,31 +19,29 @@ The tool is available under BSD-3-Clause License.
## Integration
-
-
## Usage
-!!! Example Python
+**Python**
- ```py linenums="1"
- import physiokit as pk
+```py title="Python example" linenums="1"
+import physiokit as pk
- heart_rate = 64 # BPM
- sample_rate = 1000 # Hz
- signal_length = 10*sample_rate # 10 seconds
+heart_rate = 64 # BPM
+sample_rate = 1000 # Hz
+signal_length = 10*sample_rate # 10 seconds
- # Generate NSR synthetic ECG signal
- ecg, segs, fids = pk.ecg.synthesize(
- signal_length=signal_length,
- sample_rate=sample_rate,
- heart_rate=heart_rate,
- leads=1,
- preset=pk.ecg.EcgPreset.NSR,
- p_multiplier=1.5,
- t_multiplier=1.2,
- noise_multiplier=0.2
- )
+# Generate NSR synthetic ECG signal
+ecg, segs, fids = pk.ecg.synthesize(
+ signal_length=signal_length,
+ sample_rate=sample_rate,
+ heart_rate=heart_rate,
+ leads=1,
+ preset=pk.ecg.EcgPreset.NSR,
+ p_multiplier=1.5,
+ t_multiplier=1.2,
+ noise_multiplier=0.2
+)
- ```
+```
-Synthetic signal generation is a standalone preprocessing tool, not a registered sleepKIT dataset. To use generated signals in a task, provide a [custom dataset adapter](byod.md) and matching feature extraction.
+Synthetic signal generation is a standalone preprocessing tool, not a registered sleepKIT dataset. To use generated signals in a task, provide a [custom dataset adapter](/sleepkit/datasets/byod/) and matching feature extraction.
diff --git a/docs/datasets/ysyw.md b/astro-site/src/content/docs/datasets/ysyw.mdx
similarity index 73%
rename from docs/datasets/ysyw.md
rename to astro-site/src/content/docs/datasets/ysyw.mdx
index a54d4e2..96697db 100644
--- a/docs/datasets/ysyw.md
+++ b/astro-site/src/content/docs/datasets/ysyw.mdx
@@ -1,4 +1,7 @@
-# YSYW Dataset
+---
+title: "YSYW Dataset"
+description: "A total of 1,983 PSG recordings were provided by the Massachusetts General Hospital’s (MGH) Sleep Lab in the Sleep Division together with the Computational…"
+---
## Overview
@@ -14,9 +17,8 @@ Funding was from the National Institutes of Health, grant R01-GM104987. We are a
The YSYW dataset is available commercial use under [Open Data Commons Attribution License](https://physionet.org/content/challenge-2018/view-license/1.0.0/).
-
## Supported Tasks
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
+* [Sleep Detect](/sleepkit/tasks/detect/)
+* [Sleep Stage](/sleepkit/tasks/stage/)
+* [Sleep Apnea](/sleepkit/tasks/apnea/)
diff --git a/docs/detection-annotated-dataset.md b/astro-site/src/content/docs/detection-annotated-dataset.mdx
similarity index 88%
rename from docs/detection-annotated-dataset.md
rename to astro-site/src/content/docs/detection-annotated-dataset.mdx
index c23fbb6..a3a5c60 100644
--- a/docs/detection-annotated-dataset.md
+++ b/astro-site/src/content/docs/detection-annotated-dataset.mdx
@@ -1,4 +1,7 @@
-# Training with the annotated-period target
+---
+title: "Training with the annotated-period target"
+description: "AnnotatedDataset composes the verified source, raw events, candidate policy, and frozen assignment as a read-only source adapter. It reconstructs the verified…"
+---
`AnnotatedDataset` composes the verified source, raw events, candidate policy, and
frozen assignment as a read-only source adapter. It reconstructs the verified UTC
@@ -6,7 +9,7 @@ clock and builds target arrays in memory. It neither loads historical
`sleep_stages` values nor rewrites original files. This keeps target derivation
versioned without duplicating the entire sensor dataset.
-```python
+```python title="Python example"
from sleepkit.recipes.detection.target_dataset import AnnotatedDataset
from sleepkit.recipes.detection.recipe import Config, run_membership
@@ -67,7 +70,7 @@ Every membership run retains these local files outside the public bundle:
Index creation checks every eligible target against the evaluated target sequence,
not only the total length. The index also rejects a different frozen context length.
-Its coordinates support the [common-index comparison](detection-comparison.md)
+Its coordinates support the [common-index comparison](/sleepkit/detection-comparison/)
with historical model outputs. Test prediction collection
currently retains batches in memory before writing NPZ; index writing streams by
subject. This is an offline recipe, not a causal streaming detector.
@@ -89,8 +92,8 @@ historical labels, train-only fitted state, Keras/TFLite parity, exact scored ta
metric reproduction from saved predictions, unlabeled inference, and artifact privacy.
The legacy training/inference tests remain supported.
-The [first declared experiment](detection-first-experiment.md) is complete, with
+The [first declared experiment](/sleepkit/detection-first-experiment/) is complete, with
pooled and per-series membership metrics and sampled real-input Keras/TFLite parity.
-Its read-only report can be reproduced from saved scoring evidence. The [common scoring intersection](detection-comparison.md) and
-[INT8 conversion](detection-int8.md) are documented separately. Historical training exposure, task acceptance thresholds, artifact
+Its read-only report can be reproduced from saved scoring evidence. The [common scoring intersection](/sleepkit/detection-comparison/) and
+[INT8 conversion](/sleepkit/detection-int8/) are documented separately. Historical training exposure, task acceptance thresholds, artifact
licensing and hardware validation remain separate questions.
diff --git a/docs/detection-comparison.md b/astro-site/src/content/docs/detection-comparison.mdx
similarity index 94%
rename from docs/detection-comparison.md
rename to astro-site/src/content/docs/detection-comparison.mdx
index 6e718fc..f7fd451 100644
--- a/docs/detection-comparison.md
+++ b/astro-site/src/content/docs/detection-comparison.mdx
@@ -1,12 +1,15 @@
-# Detection diagnostics and historical comparison
+---
+title: "Detection diagnostics and historical comparison"
+description: "The first experiment now has read-only error diagnostics and a separate, explicit SD-2 comparison recipe. These steps consume the same saved run evidence. They…"
+---
-The [first experiment](detection-first-experiment.md) now has read-only error
+The [first experiment](/sleepkit/detection-first-experiment/) now has read-only error
diagnostics and a separate, explicit SD-2 comparison recipe. These steps consume
the same saved run evidence. They do not retrain a model or tune a threshold.
## Error diagnostics
-```sh
+```sh title="Terminal"
python -m sleepkit.recipes.detection.error_analysis \
--run /path/to/membership-run \
--output /path/to/new-error-analysis.json
@@ -122,7 +125,7 @@ source, and output hashes also matched. No material finding remained.
## Compose the comparison in Python
-```python
+```python title="Python example"
from sleepkit.recipes.detection.comparison import compare
from sleepkit.recipes.detection.target_dataset import AnnotatedDataset
@@ -165,5 +168,5 @@ both flattened prediction arrays. These files contain identifiers and remain
outside public bundles. Existing output directories are refused. Failed runs
retain partial evidence without a completed comparison report.
-The next [fixed int8 conversion](detection-int8.md) preserves the new model's
+The next [fixed int8 conversion](/sleepkit/detection-int8/) preserves the new model's
preprocessing and measures quantization separately from this historical comparison.
diff --git a/docs/detection-evaluation-protocol.md b/astro-site/src/content/docs/detection-evaluation-protocol.mdx
similarity index 91%
rename from docs/detection-evaluation-protocol.md
rename to astro-site/src/content/docs/detection-evaluation-protocol.mdx
index be66bf7..369cf35 100644
--- a/docs/detection-evaluation-protocol.md
+++ b/astro-site/src/content/docs/detection-evaluation-protocol.mdx
@@ -1,7 +1,9 @@
-# Detection evaluation checkpoint
-
-This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](detection-annotated-dataset.md) and [comparison report](detection-comparison.md). The checkpoint discussion below records the decisions leading to that workflow.
+---
+title: "Detection evaluation checkpoint"
+description: "This page preserves a historical evaluation checkpoint. For the implemented workflow, see the annotated dataset adapter and comparison report. The checkpoint…"
+---
+This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](/sleepkit/detection-annotated-dataset/) and [comparison report](/sleepkit/detection-comparison/). The checkpoint discussion below records the decisions leading to that workflow.
The pipeline and artifact contracts are implemented. The next question is whether
a comparison is valid, before asking which model scores better. This checkpoint
@@ -12,7 +14,7 @@ It does not change source labels, select a split, or establish benchmark results
From the checkout, in an environment with NumPy and h5py:
-```sh
+```sh title="Terminal"
python -m sleepkit.recipes.detection.audit \
--data /path/to/cmidss \
--events /path/to/cmidss/train_events.csv \
@@ -146,21 +148,20 @@ At this checkpoint, raw-series alignment and annotation-policy review were
the next steps; their completed records are linked below. Historical model exposure and model licensing remain unresolved. No model
publication is authorized by producing an audit report.
-The [event-supported label policy](detection-label-policy.md) records the
+The [event-supported label policy](/sleepkit/detection-label-policy/) records the
subsequent review and adopted target. It does not overwrite the audit output.
-The [raw-source verification](detection-source-alignment.md) now confirms step/index,
+The [raw-source verification](/sleepkit/detection-source-alignment/) now confirms step/index,
UTC cadence, and channel alignment for the audited local snapshot. Its 44 local-clock
jumps coincide with timezone-offset changes. This supplies source-alignment evidence;
annotation semantics and historical training exposure remain separate open questions.
-
## Current implementation status
The audit, raw alignment, independent-clock path, candidate policy, and target-aware
-adapter are merged. The [frozen assignment and target contract](detection-frozen-split.md)
+adapter are merged. The [frozen assignment and target contract](/sleepkit/detection-frozen-split/)
record the recovered primary annotation evidence and seed-zero evaluation cohort.
-The [first experiment](detection-first-experiment.md) and
-[diagnostics/common-index comparison](detection-comparison.md) now have local
+The [first experiment](/sleepkit/detection-first-experiment/) and
+[diagnostics/common-index comparison](/sleepkit/detection-comparison/) now have local
results. Historical model exposure and artifact licensing remain unresolved;
the comparison is descriptive rather than a verified historical held-out benchmark.
diff --git a/docs/detection-first-experiment.md b/astro-site/src/content/docs/detection-first-experiment.mdx
similarity index 93%
rename from docs/detection-first-experiment.md
rename to astro-site/src/content/docs/detection-first-experiment.mdx
index 3bb5190..58cec83 100644
--- a/docs/detection-first-experiment.md
+++ b/astro-site/src/content/docs/detection-first-experiment.mdx
@@ -1,4 +1,7 @@
-# First frozen-cohort membership experiment
+---
+title: "First frozen-cohort membership experiment"
+description: "The first new detection recipe run completed on 2026-09-20. Its final Keras model achieved 95.7657% accuracy and 0.955611 macro-F1 on the frozen test set. This…"
+---
The first new detection recipe run completed on 2026-09-20. Its final Keras model
achieved **95.7657% accuracy and 0.955611 macro-F1** on the frozen test set.
@@ -25,7 +28,7 @@ The frozen series assignment and retained contexts were:
The split file SHA-256 is
`08c2ac221b3212b5589d29f623015994da8c6fd104708879b40bcb4db60306e7`.
-The [annotated dataset adapter](detection-annotated-dataset.md) reconstructs targets
+The [annotated dataset adapter](/sleepkit/detection-annotated-dataset/) reconstructs targets
from verified events and clocks; it ignores historical `sleep_stages` arrays.
Preprocessing v3 uses five features, 60-second windows, and a 30-second stride.
Normalization fits all valid frames from the 193 training series, including
@@ -96,7 +99,7 @@ For a completed membership run, the read-only evaluation helper needs NumPy and
the local scoring evidence, but does not load TensorFlow, source recordings, or
the model:
-```sh
+```sh title="Terminal"
python -m sleepkit.recipes.detection.evaluation \
--run /path/to/run \
--output /path/to/new-evaluation.json
@@ -123,7 +126,7 @@ committed with this report.
## Next evidence gates
-The [error diagnostics and historical comparison](detection-comparison.md) now
+The [error diagnostics and historical comparison](/sleepkit/detection-comparison/) now
report series, context-position, and observed-transition errors and compare both
pipelines on an exact common scoring intersection. Any changes informed by these
test reports must be declared; the current test set is no longer untouched for
diff --git a/docs/detection-frozen-split.md b/astro-site/src/content/docs/detection-frozen-split.mdx
similarity index 91%
rename from docs/detection-frozen-split.md
rename to astro-site/src/content/docs/detection-frozen-split.mdx
index ff6d180..5eaf998 100644
--- a/docs/detection-frozen-split.md
+++ b/astro-site/src/content/docs/detection-frozen-split.mdx
@@ -1,9 +1,12 @@
-# Frozen evaluation assignment and target
+---
+title: "Frozen evaluation assignment and target"
+description: "The reviewed audit/clock/candidate stack (#22–#25) is integrated into main. This checkpoint defines the derived target and freezes a reproducible split. It is…"
+---
The reviewed audit/clock/candidate stack (#22–#25) is integrated into `main`.
This checkpoint defines the derived target and freezes a reproducible split. It
is assignment-only: running the existing recipe with `split.json` still reads
-historical HDF5 labels. The separate [annotated dataset recipe](detection-annotated-dataset.md) applies the
+historical HDF5 labels. The separate [annotated dataset recipe](/sleepkit/detection-annotated-dataset/) applies the
derived target and writes exact scoring evidence.
## Target: annotated nightly-period membership
@@ -30,7 +33,7 @@ model output names remain unchanged; future dataset/model artifacts must carry
Source retrieval (public, no credentials):
-```sh
+```sh title="Terminal"
curl -s https://www.kaggle.com/api/i/competitions.PageService/ListPages \
-H 'Content-Type: application/json' --data '{"competitionId":53666}'
```
@@ -43,7 +46,7 @@ identity statement; no independent person-linkage audit was performed.
## Deterministic assignment
-```sh
+```sh title="Terminal"
uv run python -m sleepkit.recipes.detection.split \
--data /path/to/original-cmidss --coverage /path/to/candidate-coverage.json \
--output /path/to/new-frozen-split --seed 0
@@ -86,6 +89,6 @@ training exposure remains unknown, so this new split cannot certify that model
as held out. Preserve historical preprocessing and treat its results as descriptive
until exposure evidence exists.
-The [read-only target adapter](detection-annotated-dataset.md) now derives labels
+The [read-only target adapter](/sleepkit/detection-annotated-dataset/) now derives labels
in memory from verified events, retains unknown masks, uses this frozen assignment,
and persists exact scoring indices with target-specific artifact metadata.
diff --git a/docs/detection-golden.md b/astro-site/src/content/docs/detection-golden.mdx
similarity index 90%
rename from docs/detection-golden.md
rename to astro-site/src/content/docs/detection-golden.mdx
index 270d3c4..4d39b2d 100644
--- a/docs/detection-golden.md
+++ b/astro-site/src/content/docs/detection-golden.mdx
@@ -1,4 +1,7 @@
-# Detection golden baseline
+---
+title: "Detection golden baseline"
+description: "experiments/detection-golden.json defines a public reconstruction of the first annotated-period membership run. It records the exact recipe configuration,…"
+---
`experiments/detection-golden.json` defines a public reconstruction of the first
annotated-period membership run. It records the exact recipe configuration,
@@ -17,7 +20,7 @@ This is a reconstruction definition, not a universal runner or a release
manifest. The ordinary Python entry point validates the supplied local evidence
against the pinned aggregate hashes and then calls `run_membership`:
-```sh
+```sh title="Terminal"
python experiments/run_detection_golden.py \
--data /path/to/original-cmidss \
--events /path/to/train_events.csv \
@@ -40,7 +43,7 @@ definition and runner hash remain attached to that run.
Performance measurements are a separate concern; use the bounded ordinary-Python
profiler at `python -m sleepkit.recipes.detection.profile` with the same local
-dataset evidence; see the [profiling guide](detection-profiling.md). Its results
+dataset evidence; see the [profiling guide](/sleepkit/detection-profiling/). Its results
are not part of this golden quality reference.
The target is `sleepkit.annotated_period_membership/v1`: class 0 is
@@ -84,8 +87,8 @@ These are observed reference values from one recorded run. They are not
prospective acceptance thresholds or quality gates. Seeded execution is not a
bitwise reproducibility guarantee across environments, and a run from the current
checkout is expected to be a reconstruction rather than a byte-identical replay.
-The [first experiment report](detection-first-experiment.md) and
-[annotated target adapter](detection-annotated-dataset.md) provide the surrounding
+The [first experiment report](/sleepkit/detection-first-experiment/) and
+[annotated target adapter](/sleepkit/detection-annotated-dataset/) provide the surrounding
evidence and interpretation. Exposure of a separate historical SD-2 comparator to
this cohort remains unresolved; that question does not qualify this newly trained
frozen-split baseline.
@@ -94,6 +97,6 @@ The vectorized preparation revision advances only the current preprocessing
implementation pin. The original module hashes remain under `historical_run`, and
the original definition remains available at commit
`042c1eef5608db3bb842f29c6f12b768663f9026`. The
-[preparation equivalence report](detection-preparation-performance.md) binds the
+preparation equivalence report binds the
revised implementation to exact scalar-reference comparisons. Historical quality
metrics remain observations from the original five-epoch run.
diff --git a/docs/detection-int8.md b/astro-site/src/content/docs/detection-int8.mdx
similarity index 93%
rename from docs/detection-int8.md
rename to astro-site/src/content/docs/detection-int8.mdx
index 07ba35a..86fe6d6 100644
--- a/docs/detection-int8.md
+++ b/astro-site/src/content/docs/detection-int8.mdx
@@ -1,13 +1,16 @@
-# Fixed int8 conversion and release preparation
+---
+title: "Fixed int8 conversion and release preparation"
+description: "This step converts the first membership experiment without retraining or replacing its fitted preprocessing. It preserves the original float TFLite and Keras…"
+---
-This step converts the [first membership experiment](detection-first-experiment.md)
+This step converts the [first membership experiment](/sleepkit/detection-first-experiment/)
without retraining or replacing its fitted preprocessing. It preserves the original
float TFLite and Keras bytes and measures the quantized model on exactly the same
eligible test outputs.
## Run the Python recipe
-```python
+```python title="Python example"
from sleepkit.recipes.detection.quantization import quantize_run
# source is the same AnnotatedDataset used for the original run.
@@ -116,7 +119,7 @@ per model with bitwise-identical outputs. No material finding remained.
The existing raw-sensor entry point supports both bundled models:
-```python
+```python title="Python example"
from sleepkit.recipes.detection.inference import predict
integer = predict("int8-run/bundle", sensor_data, sample_time=utc_seconds)
@@ -142,11 +145,11 @@ The local experiment directory additionally retains the declaration, private
calibration evidence, per-series evaluation, and exact int8/float test arrays.
Staging refuses existing output directories and preserves the original run.
Once release rights and terms are established, use the generic
-[`stage-release` operation](huggingface-artifacts.md#stage-a-licensed-release-from-an-experiment)
+[`stage-release` operation](/sleepkit/huggingface-artifacts/#stage-a-licensed-release-from-an-experiment)
to add the selected license, public decision record and release card without
reconverting the models or replacing their validation evidence.
-```sh
+```sh title="Terminal"
python -m sleepkit.artifacts validate /path/to/int8-run/bundle \
--profile runnable --runtime
python -m sleepkit.artifacts publish /path/to/int8-run/bundle \
@@ -156,7 +159,7 @@ python -m sleepkit.artifacts publish /path/to/int8-run/bundle \
The second command is a local dry run. The repository name is a proposed dedicated
destination, not an existing deployment. Upload requires an explicitly chosen model
artifact license and the `--upload` option; source-code licensing is not assumed to
-cover model weights. The [licensing policy](model-licensing-policy.md) records
+cover model weights. The [licensing policy](/sleepkit/model-licensing-policy/) records
CC BY-NC-SA 4.0 without an Ambiq hardware restriction as the conservative candidate
for this CMIDSS model. Data-access, training-purpose and model-redistribution facts
still need to be recorded before release; choosing an NC label alone does not
diff --git a/docs/detection-label-policy.md b/astro-site/src/content/docs/detection-label-policy.mdx
similarity index 90%
rename from docs/detection-label-policy.md
rename to astro-site/src/content/docs/detection-label-policy.mdx
index be9fdb0..7ecb177 100644
--- a/docs/detection-label-policy.md
+++ b/astro-site/src/content/docs/detection-label-policy.mdx
@@ -1,7 +1,9 @@
-# Candidate event-supported label policy
-
-This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](detection-annotated-dataset.md) and [comparison report](detection-comparison.md). The checkpoint discussion below records the decisions leading to that workflow.
+---
+title: "Candidate event-supported label policy"
+description: "This page preserves a historical evaluation checkpoint. For the implemented workflow, see the annotated dataset adapter and comparison report. The checkpoint…"
+---
+This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](/sleepkit/detection-annotated-dataset/) and [comparison report](/sleepkit/detection-comparison/). The checkpoint discussion below records the decisions leading to that workflow.
Status: implemented candidate policy `sleepkit.event_candidates/v1`, separate from
the active training label policy. No existing HDF5 labels or historical model inputs are rewritten here.
@@ -66,7 +68,7 @@ available event timestamp directly with raw UTC at its source step (pair duratio
alone cannot detect an equal shift of both timestamps), and test a pure interval
builder that enforces consecutive integer night IDs and excludes incomplete or
conflicting intervening groups. The optional event-clock audit now implements the first check; see
-[independent sample clocks](detection-sample-clock.md). The pure interval builder and read-only coverage audit are now implemented.
+[independent sample clocks](/sleepkit/detection-sample-clock/). The pure interval builder and read-only coverage audit are now implemented.
Annotation-semantics review remains pending before these candidates become
evaluation ground truth.
@@ -77,13 +79,12 @@ sample clock. A source alignment report can establish that a particular snapshot
is continuous in UTC even when local clocks jump. That finding does not justify
accepting arbitrary one-hour jumps from other inputs.
-The [verified source adapter](detection-sample-clock.md) supplies an explicit UTC sample
+The [verified source adapter](/sleepkit/detection-sample-clock/) supplies an explicit UTC sample
clock alongside local TS. Validate cadence against that clock, use local TS only
for time-of-day features, and carry the clock contract through training and
unlabeled inference. Keep the existing strict check for inputs without sufficient
clock evidence. Do not add a global option that simply disables cadence checks.
-
## Pure builder and conflict rules
`candidate_labels.build_candidates(nights, sample_count, first_utc_seconds=...)`
@@ -108,7 +109,7 @@ nights. Shuffling rows and groups leaves the result unchanged.
## Read-only coverage audit
-```sh
+```sh title="Terminal"
uv run python -m sleepkit.recipes.detection.candidate_audit \
--data /path/to/original-cmidss --events /path/to/train_events.csv \
--alignment /path/to/passed-event-clock-alignment.json \
@@ -149,10 +150,10 @@ population, but this is not a model benchmark or evidence of label correctness.
The [official competition overview](https://www.kaggle.com/competitions/child-mind-institute-detect-sleep-states)
defines an event-detection task evaluated by average precision across timestamp
tolerances. This does not by itself establish dense clinical sleep/wake ground truth.
-The [retrieved annotation contract and frozen split](detection-frozen-split.md)
+The [retrieved annotation contract and frozen split](/sleepkit/detection-frozen-split/)
now support a derived annotated-period membership target, with explicit inside,
outside-supported-period, and unknown semantics. They do not support clinical
per-sample sleep/wake claims. The builder's historical candidate names remain
unchanged; future training artifacts must declare the adopted target explicitly.
-The [annotated dataset adapter and scoring index](detection-annotated-dataset.md)
+The [annotated dataset adapter and scoring index](/sleepkit/detection-annotated-dataset/)
now implement this contract without changing original labels.
diff --git a/docs/detection-profiling.md b/astro-site/src/content/docs/detection-profiling.mdx
similarity index 92%
rename from docs/detection-profiling.md
rename to astro-site/src/content/docs/detection-profiling.mdx
index 184b5ca..658126e 100644
--- a/docs/detection-profiling.md
+++ b/astro-site/src/content/docs/detection-profiling.mdx
@@ -1,4 +1,7 @@
-# Profiling the detection recipe
+---
+title: "Profiling the detection recipe"
+description: "The profiler measures the existing sleepKIT TensorFlow membership recipe before we change its loader. It calls the same feature preparation, normalization,…"
+---
The profiler measures the existing sleepKIT TensorFlow membership recipe before
we change its loader. It calls the same feature preparation, normalization,
@@ -8,9 +11,9 @@ validation/test predictions, choose a checkpoint, export a model or publish to H
Whole-cohort integrity checks still hash the frozen source files.
Run from a fresh process with the detection dependencies installed. Use the
-frozen dataset inputs described in [the golden experiment](detection-golden.md):
+frozen dataset inputs described in [the golden experiment](/sleepkit/detection-golden/):
-```sh
+```sh title="Terminal"
TF_NUM_INTRAOP_THREADS=2 TF_NUM_INTEROP_THREADS=1 OMP_NUM_THREADS=2 \
python -m sleepkit.recipes.detection.profile \
--data "$DATA" --events "$EVENTS" \
@@ -85,7 +88,7 @@ Keep prediction-quality reproduction separate from performance experiments.
## First CPU observation
-The [2026-09-20 evidence](evidence/membership-tcn-seed0-cpu-20260920/report.json)
+The [2026-09-20 evidence](/sleepkit/evidence/membership-tcn-seed0-cpu-20260920/report.json)
contains the declaration, environment and report for the frozen membership training
partition: 193 series, 14,857,307 valid normalization frames, 34,474 eligible
contexts, 1,078 batches, and ten contexts in the final batch. No held-out feature
@@ -116,4 +119,4 @@ do not establish a TensorFlow backend bottleneck. Candidate optimizations must
preserve the recorded feature/normalizer and sample contracts and be compared in
repeated, controlled runs before any improvement claim.
-The next measured change is [bounded vectorized feature preparation](detection-preparation-performance.md), with exact scalar-reference comparisons before reusing the existing feature contract.
+The next measured change is bounded vectorized feature preparation, with exact scalar-reference comparisons before reusing the existing feature contract.
diff --git a/docs/detection-recipe.md b/astro-site/src/content/docs/detection-recipe.mdx
similarity index 90%
rename from docs/detection-recipe.md
rename to astro-site/src/content/docs/detection-recipe.mdx
index d897de6..e13f669 100644
--- a/docs/detection-recipe.md
+++ b/astro-site/src/content/docs/detection-recipe.mdx
@@ -1,10 +1,13 @@
-# A detection pipeline written in Python
+---
+title: "A detection pipeline written in Python"
+description: "The new detection recipe is developed alongside the legacy task CLI. It reads CMIDSS sensor-channel HDF5 files and owns feature generation, normalization,…"
+---
The new detection recipe is developed alongside the legacy task CLI. It reads
CMIDSS sensor-channel HDF5 files and owns feature generation, normalization,
training, held-out evaluation, and artifact export. It uses ordinary functions,
a small config, a native Keras model, and the shared artifact package from
-[the HF publishing workflow](huggingface-artifacts.md).
+[the HF publishing workflow](/sleepkit/huggingface-artifacts/).
This is an experimental major-version building block. It does not reproduce the
historical SD-2-TCN-SM model. Global training-only normalization, invalid-data
@@ -19,7 +22,7 @@ CPU. TensorBoard is now an explicit dependency because legacy training uses its
callback and TF 2.21 no longer brings it in transitively. The original SleepKit
training dependencies remain installed; a full dependency split is later work.
-```sh
+```sh title="Terminal"
uv sync --extra detection
uv run --extra detection python -m sleepkit.recipes.detection smoke --output /tmp/detection-smoke
```
@@ -63,7 +66,7 @@ pair sleep events, or silently resample irregular signals.
Write a local subject split with three nonempty, disjoint partitions:
-```json
+```json title="JSON example"
{
"train": ["subject-a", "subject-b"],
"validation": ["subject-c"],
@@ -76,7 +79,7 @@ contributes to fitted normalization. For datasets with multiple recordings per
person, the adapter must group them under the same subject before creating splits;
this CMIDSS adapter treats each source series file as one subject.
-```sh
+```sh title="Terminal"
uv run --extra detection python -m sleepkit.recipes.detection train \
--data /path/to/cmidss --split /path/to/split.json \
--output /path/to/new-run --cache /path/to/local-feature-cache \
@@ -98,7 +101,7 @@ of each source timestamp: `mean(cos(2*pi*TS/86400))`. Encoding before averaging
keeps windows spanning midnight close to +1 rather than interpreting them as noon.
The v2 contract corrected the original time-of-day formula. The default v3
contract additionally validates continuity with an independent UTC sample clock;
-see [sample-clock alignment](detection-sample-clock.md).
+see [sample-clock alignment](/sleepkit/detection-sample-clock/).
Old v1 caches are bypassed, and v1 fitted states are rejected by this implementation.
Retrain and export a new bundle; do not pair v1 model weights or normalization with
v2 or v3 features. Historical baseline packaging and its original feature requirements
@@ -129,7 +132,7 @@ an incremental reader in a later adapter.
## Compose an experiment
-```python
+```python title="Python example"
from sleepkit.recipes.detection.recipe import Config, run
run(data_root, split_file, output_dir, Config(epochs=10),
@@ -145,7 +148,7 @@ This logits contract belongs to this recipe, not the generic artifact format.
Experiments can also import and call individual steps directly:
-```python
+```python title="Python example"
from sleepkit.recipes.detection.data import load_split, subject_features
from sleepkit.recipes.detection.preprocessing import Normalizer
@@ -182,7 +185,7 @@ fingerprints in the bundle verify a known local run, but cannot reconstruct its
private data. Metrics report the provided labels, not clinical accuracy. No task
acceptance threshold is implied by successful evaluation or runtime conformance.
-```sh
+```sh title="Terminal"
python -m sleepkit.artifacts validate /path/to/run/bundle --profile runnable --runtime
python -m sleepkit.recipes.detection predict \
--bundle /path/to/run/bundle --data /path/to/cmidss \
@@ -198,6 +201,6 @@ using the artifact API. License choice and publication are separate release work
## Validation scope
-The [first experiment](detection-first-experiment.md), [historical comparison](detection-comparison.md), and [INT8 conversion](detection-int8.md) document separate completed checkpoints and their evidence. Read their declared populations, target semantics and limitations before comparing results. These reports do not establish MCU validation or equivalence to a clinical sleep/wake task.
+The [first experiment](/sleepkit/detection-first-experiment/), [historical comparison](/sleepkit/detection-comparison/), and [INT8 conversion](/sleepkit/detection-int8/) document separate completed checkpoints and their evidence. Read their declared populations, target semantics and limitations before comparing results. These reports do not establish MCU validation or equivalence to a clinical sleep/wake task.
-The export path uses the native [Keras export API](https://keras.io/api/models/model_saving_apis/export/) and [TensorFlow-to-LiteRT conversion](https://developers.google.com/edge/litert/conversion/tensorflow/convert_tf). The [evaluation checkpoint](detection-evaluation-protocol.md) records the annotation audit and comparison requirements.
+The export path uses the native [Keras export API](https://keras.io/api/models/model_saving_apis/export/) and [TensorFlow-to-LiteRT conversion](https://developers.google.com/edge/litert/conversion/tensorflow/convert_tf). The [evaluation checkpoint](/sleepkit/detection-evaluation-protocol/) records the annotation audit and comparison requirements.
diff --git a/docs/detection-sample-clock.md b/astro-site/src/content/docs/detection-sample-clock.mdx
similarity index 92%
rename from docs/detection-sample-clock.md
rename to astro-site/src/content/docs/detection-sample-clock.mdx
index 6ecd7f5..8c45a6d 100644
--- a/docs/detection-sample-clock.md
+++ b/astro-site/src/content/docs/detection-sample-clock.mdx
@@ -1,4 +1,7 @@
-# Independent sample clocks
+---
+title: "Independent sample clocks"
+description: "Detection preprocessing v3 accepts local TS/ENMO/ZANGLE values plus an optional independent sampletime vector. It must contain signed int64 Unix seconds, align…"
+---
Detection preprocessing v3 accepts local TS/ENMO/ZANGLE values plus an optional
independent `sample_time` vector. It must contain signed int64 Unix seconds, align
@@ -6,7 +9,7 @@ one-to-one with source samples, and increase by exactly five seconds. UTC contro
sampling continuity; local TS still supplies the cyclic time-of-day feature. Without
an independent clock, the existing strict local-TS cadence check applies.
-```python
+```python title="Python example"
from sleepkit.recipes.detection.preprocessing import prepare
from sleepkit.recipes.detection.inference import predict
@@ -37,11 +40,11 @@ Use a fresh source-alignment report containing `first_utc_seconds` to build a se
clocked dataset. Only a successful report with matching source hashes can support
reconstruction of the regular UTC sequence. Older reports must be regenerated.
The clock materializer preserves historical labels; it does not implement the
-[candidate label policy](detection-label-policy.md).
+[candidate label policy](/sleepkit/detection-label-policy/).
## Event clock evidence
-```sh
+```sh title="Terminal"
uv run --extra source-audit python -m sleepkit.recipes.detection.alignment \
--data /path/to/cmidss --parquet /path/to/train_series.parquet \
--events /path/to/train_events.csv --output /path/to/new-alignment.json
@@ -55,7 +58,7 @@ requested audit; an entirely missing event set does not pass. The report binds t
events file hash and detects file changes during verification.
This verifies event timing, not sleep/wake semantics, independent-person grouping,
-or historical model training exposure. The [candidate interval builder and coverage audit](detection-label-policy.md) are
+or historical model training exposure. The [candidate interval builder and coverage audit](/sleepkit/detection-label-policy/) are
implemented separately. Annotation-protocol review remains a gate before benchmarking.
On the audited local snapshot, all 9,585 available event rows match raw UTC exactly;
@@ -66,7 +69,7 @@ These results apply only to the source hashes in the local report.
To copy explicitly selected subjects with verified clocks:
-```sh
+```sh title="Terminal"
uv run python -m sleepkit.recipes.detection.clock_source \
--data /path/to/cmidss --alignment /path/to/new-alignment.json \
--output /path/to/new-clocked-source --subjects subject_a subject_b
diff --git a/docs/detection-source-alignment.md b/astro-site/src/content/docs/detection-source-alignment.mdx
similarity index 87%
rename from docs/detection-source-alignment.md
rename to astro-site/src/content/docs/detection-source-alignment.mdx
index a5336aa..cabac69 100644
--- a/docs/detection-source-alignment.md
+++ b/astro-site/src/content/docs/detection-source-alignment.mdx
@@ -1,10 +1,13 @@
-# Raw-source alignment verification
+---
+title: "Raw-source alignment verification"
+description: "This check establishes whether the legacy HDF5 sensor rows match the raw Parquet series, independently of local time-of-day changes. It is separate from…"
+---
This check establishes whether the legacy HDF5 sensor rows match the raw Parquet
series, independently of local time-of-day changes. It is separate from annotation
coverage, person identity, and model evaluation.
-```sh
+```sh title="Terminal"
uv sync --extra detection --extra source-audit
uv run --extra source-audit python -m sleepkit.recipes.detection.alignment \
--data /path/to/cmidss --parquet /path/to/cmidss/train_series.parquet \
@@ -48,13 +51,13 @@ person, or that historical model training excluded any particular subject.
## Reader change supported by this evidence
The legacy detector path validates cadence using local TS and rejects these 44 files.
-The [independent sample-clock adapter](detection-sample-clock.md) now preserves an explicit UTC clock alongside
+The [independent sample-clock adapter](/sleepkit/detection-sample-clock/) now preserves an explicit UTC clock alongside
local TS, validates continuity against it, and uses local TS only for the time-of-day
feature. This contract carries through caching, training, and unlabeled inference.
Inputs without independent clock evidence retain the strict local-TS check.
-The [event-supported label policy](detection-label-policy.md) records the adopted
-derived annotated-period membership target. The [dataset adapter](detection-annotated-dataset.md)
+The [event-supported label policy](/sleepkit/detection-label-policy/) records the adopted
+derived annotated-period membership target. The [dataset adapter](/sleepkit/detection-annotated-dataset/)
implements that target without overwriting source labels.
## Parquet dependency compatibility
diff --git a/docs/features/byofs.md b/astro-site/src/content/docs/features/byofs.mdx
similarity index 82%
rename from docs/features/byofs.md
rename to astro-site/src/content/docs/features/byofs.mdx
index cae028a..b638491 100644
--- a/docs/features/byofs.md
+++ b/astro-site/src/content/docs/features/byofs.mdx
@@ -1,4 +1,7 @@
-# Bring-Your-Own-Features (BYOFS)
+---
+title: "Bring-Your-Own-Features (BYOFS)"
+description: "The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to sleepKIT to be used with built-in or custom tasks."
+---
The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to sleepKIT to be used with built-in or custom tasks.
@@ -6,7 +9,7 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
1. **Create a Feature Set**: Define a new feature set class that subclasses `sk.FeatureSet` and implements the feature contract. The following is a skeleton: implement the writer before calling it.
- ```py linenums="1"
+ ```py title="Python example" linenums="1"
import sleepkit as sk
class CustomFeatureSet(sk.FeatureSet):
@@ -25,14 +28,14 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
2. **Register the Feature Set**: Register the new feature set with the `sk.FeatureFactory` by calling the `register` method. This method takes the feature set name and the feature set class as arguments.
- ```py linenums="1"
+ ```py title="Python example" linenums="1"
import sleepkit as sk
sk.FeatureFactory.register(CustomFeatureSet.name(), CustomFeatureSet)
```
3. **Use the Feature Set**: The new feature set can now be used to generate feature sets.
- ```py linenums="1"
+ ```py title="Python example" linenums="1"
import sleepkit as sk
from pathlib import Path
diff --git a/docs/features/fs_c_ear_9.md b/astro-site/src/content/docs/features/fs_c_ear_9.mdx
similarity index 77%
rename from docs/features/fs_c_ear_9.md
rename to astro-site/src/content/docs/features/fs_c_ear_9.mdx
index 4e53777..e109f1e 100644
--- a/docs/features/fs_c_ear_9.md
+++ b/astro-site/src/content/docs/features/fs_c_ear_9.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-C-EAR-9
+---
+title: "Feature Set: FS-C-EAR-9"
+description: "This feature set is targeted for sleep stage classification based on sensor data available from chest location. The feature set computes heart rate (HR), heart…"
+---
## Overview
@@ -14,7 +17,7 @@ The target location for this feature set is the __chest__. From this location, t
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset does not directly provide accelerometer data from the chest. However, the dataset does provide respiratory signals (RIP) captured from both chest and abdomen. In place of accelerometer data, we use filtered chest respiratory signals as a proxy for body movement features.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset does not directly provide accelerometer data from the chest. However, the dataset does provide respiratory signals (RIP) captured from both chest and abdomen. In place of accelerometer data, we use filtered chest respiratory signals as a proxy for body movement features.
## Features
@@ -32,7 +35,6 @@ This feature set includes the following 9 features:
| rsp_bpm | Mean respiration rate derived from the respiratory signal | RSP |
| hrv_qos | Quality of signal derived from HRV | ECG |
-
## Output
The feature set is stored as HDF5 files (`.h5`) with one file per subject with path: `{save_path}/{dataset}/{subject_id}.h5`. Each HDF5 file includes the following entries:
diff --git a/docs/features/fs_h_e_10.md b/astro-site/src/content/docs/features/fs_h_e_10.mdx
similarity index 83%
rename from docs/features/fs_h_e_10.md
rename to astro-site/src/content/docs/features/fs_h_e_10.mdx
index 455193c..ff85971 100644
--- a/docs/features/fs_h_e_10.md
+++ b/astro-site/src/content/docs/features/fs_h_e_10.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-H-E-10
+---
+title: "Feature Set: FS-H-E-10"
+description: "This feature set is targeted for sleep stage classification based on single pair of EEG and EOG sensor data collected on head location. The feature set…"
+---
## Overview
@@ -13,7 +16,7 @@ The target location for this feature set is the __head__. From this location, th
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset provides EEG, EOG, and EMG data from the head location. The dataset also provides sleep stage labels.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset provides EEG, EOG, and EMG data from the head location. The dataset also provides sleep stage labels.
## Features
diff --git a/docs/features/fs_w_a_5.md b/astro-site/src/content/docs/features/fs_w_a_5.mdx
similarity index 78%
rename from docs/features/fs_w_a_5.md
rename to astro-site/src/content/docs/features/fs_w_a_5.mdx
index 9d6a48e..7d5ebda 100644
--- a/docs/features/fs_w_a_5.md
+++ b/astro-site/src/content/docs/features/fs_w_a_5.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-W-A-5
+---
+title: "Feature Set: FS-W-A-5"
+description: "This feature set is targeted towards actigraphy style sleep detection using only IMU based sensor data available from wrist location. The feature set computes…"
+---
## Overview
@@ -12,7 +15,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Dataset Support
-- **[CMIDSS](../datasets/cmidss.md)**: This dataset provides pre-computed movement and z-angle data from the wrist location every 5 seconds.
+- **[CMIDSS](/sleepkit/datasets/cmidss/)**: This dataset provides pre-computed movement and z-angle data from the wrist location every 5 seconds.
## Features
@@ -26,7 +29,6 @@ This feature set includes the following 5 features:
| angle_mu | Mean z-angle | IMU |
| angle_std | Standard deviation of z-angle | IMU |
-
## Output
The feature set is stored as HDF5 files (`.h5`) with one file per subject with path: `{save_path}/{dataset}/{subject_id}.h5`. Each HDF5 file includes the following entries:
diff --git a/docs/features/fs_w_p_5.md b/astro-site/src/content/docs/features/fs_w_p_5.mdx
similarity index 78%
rename from docs/features/fs_w_p_5.md
rename to astro-site/src/content/docs/features/fs_w_p_5.mdx
index 898a203..eed6aaf 100644
--- a/docs/features/fs_w_p_5.md
+++ b/astro-site/src/content/docs/features/fs_w_p_5.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-W-P-5
+---
+title: "Feature Set: FS-W-P-5"
+description: "This feature set is targeted for sleep apnea classification based on sensor data available from wrist location. The generator computes various features over…"
+---
## Overview
@@ -12,7 +15,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset does not directly provide dual PPG, however, the dataset does provide SpO2 and single channel PPG which is sufficient.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset does not directly provide dual PPG, however, the dataset does provide SpO2 and single channel PPG which is sufficient.
## Features
diff --git a/docs/features/fs_w_pa_14.md b/astro-site/src/content/docs/features/fs_w_pa_14.mdx
similarity index 79%
rename from docs/features/fs_w_pa_14.md
rename to astro-site/src/content/docs/features/fs_w_pa_14.mdx
index af9a3e8..c5af344 100644
--- a/docs/features/fs_w_pa_14.md
+++ b/astro-site/src/content/docs/features/fs_w_pa_14.mdx
@@ -1,4 +1,7 @@
-# Feature Set: FS-W-PA-14
+---
+title: "Feature Set: FS-W-PA-14"
+description: "This feature set is targeted for sleep stage classification based on sensor data available from wrist location. The feature set computes heart rate, heart rate…"
+---
## Overview
@@ -13,7 +16,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Dataset Support
-- **[MESA](../datasets/mesa.md)**: This dataset does not directly provide dual PPG nor Accelerometer data from the wrist. However, the dataset does provide SpO2 and single channel PPG which is sufficient for PPG derived features. In place of Accelerometer data, we use leg movement as a proxy for arm movement features.
+- **[MESA](/sleepkit/datasets/mesa/)**: This dataset does not directly provide dual PPG nor Accelerometer data from the wrist. However, the dataset does provide SpO2 and single channel PPG which is sufficient for PPG derived features. In place of Accelerometer data, we use leg movement as a proxy for arm movement features.
## Features
@@ -36,7 +39,6 @@ This feature set includes the following 14 features:
| spo2_qos | Quality of signal derived from SpO2 | PPG |
| hrv_qos | Quality of signal derived from HRV | PPG |
-
## Output
The feature set is stored as HDF5 files (`.h5`) with one file per subject with path: `{save_path}/{dataset}/{subject_id}.h5`. Each HDF5 file includes the following entries:
diff --git a/astro-site/src/content/docs/features/index.mdx b/astro-site/src/content/docs/features/index.mdx
new file mode 100644
index 0000000..bc6b658
--- /dev/null
+++ b/astro-site/src/content/docs/features/index.mdx
@@ -0,0 +1,173 @@
+---
+title: "Features"
+description: "sleepKIT includes a mini feature store to enable crafting rich feature sets to train and evaluate models. The store includes several built-in feature set…"
+---
+
+import ConfigExample from "../../../components/ConfigExample.astro";
+
+__sleepKIT__ includes a mini _feature store_ to enable crafting rich feature sets to train and evaluate models. The store includes several built-in feature set generators that can be invoked to create feature sets for a variety of use cases. Each feature set inherits from `sk.FeatureSet` and provides implementations for generating features from the dataset.
+
+The main method, `generate_subject_features` receives the target dataset name, subject id, and high-level `sk.TaskParams` which includes field `feature` which includes feature set specific parameters. The resulting data and labels are stored in HDF5 format that can then be used for training via `sk.H5Dataloader` class. Custom feature set generators can also be added to the feature store by subclassing `sk.FeatureSet` and registering the new generator with the feature store.
+
+
+
+1. Load the configuration data (e.g. `configuration.json`)
+1. Load datasets from DatasetFactory (e.g. `mesa`)
+1. Load feature generator from FeatureFactory (e.g. `FS-W-PA-14`)
+1. Generate features for each dataset/subject (e.g. `generate_subject_features`)
+1. Save subjects features to disk (e.g. `subject.h5`)
+
+
+
+**Example configuration**
++ +```mermaid +graph TD +A("`Load +configuration +__TaskParams__ +`") +B("`Load datasets +__DatasetFactory__ +`") +C("`Load feature +generator +__FeatureFactory__ +`") +D("`Generate +features +`") +E("`Save +features +`") + +A ==> B +B ==> C +C ==> D +D ==> E + +``` + +--- + +## Available Feature Sets + +- **[FS-W-PA-14](/sleepkit/features/fs_w_pa_14/)**:__14__ features derived from __PPG__ and __IMU__ on __wrist__ for __sleep stage__ classification. +- **[FS-C-EAR-9](/sleepkit/features/fs_c_ear_9/)**: __9__ features derived from __ECG__, __RSP__, and __IMU__ on __chest__ for __sleep stage__ classification. +- **[FS-W-A-5](/sleepkit/features/fs_w_a_5/)**: __5__ features derived from __IMU__ on __wrist__ for actigraphy style __sleep detection__. +- **[FS-H-E-10](/sleepkit/features/fs_h_e_10/)**: __10__ features derived from __ECG__ and __EOG__ on __head__ for __sleep stage__ classification. +- **[FS-W-P-5](/sleepkit/features/fs_w_p_5/)**: __5__ features derived from __PPG__ on __wrist__ for __sleep apnea__ classification. +- **[BYOFS](/sleepkit/features/byofs/)**: Bring-Your-Own-Feature-Set (BYOFS) to create custom feature sets. + +## Feature Factory + +The feature factory, `sk.FeatureFactory`, provides a convenient way to access the feature sets. The factory is a thread-safe singleton class that provides a single point of access to the features via the features' slug names. The benefit of using the factory is it allows registering new additional feature sets that can then be leveraged by existing and new tasks. + +The feature factory provides the following methods: + +* **sk.FeatureFactory.register**: Register a custom feature set +* **sk.FeatureFactory.unregister**: Unregister a custom feature set +* **sk.FeatureFactory.has**: Check if a feature set is registered +* **sk.FeatureFactory.get**: Get a feature set +* **sk.FeatureFactory.list**: List all available feature sets diff --git a/astro-site/src/content/docs/guides/index.mdx b/astro-site/src/content/docs/guides/index.mdx new file mode 100644 index 0000000..76072a0 --- /dev/null +++ b/astro-site/src/content/docs/guides/index.mdx @@ -0,0 +1,34 @@ +--- +title: "User guide" +description: "Build a sleepKIT workflow from datasets, feature extraction and model architectures. Use the guides below to configure each step, then follow a tutorial for a…" +--- + +Build a sleepKIT workflow from datasets, feature extraction and model architectures. Use the guides below to configure each step, then follow a tutorial for a complete experiment. + +## Run an experiment + +Start with a task configuration and work through the modes you need. + +Configure a run +Download data +Train +Evaluate +Export +Run a demo + +## Choose your components + +- **Datasets** provide recordings and labels for your task. Review each dataset's access requirements and terms. +- **Feature sets** transform recordings into inputs for training and evaluation. +- **Model architectures** define the network and its configurable parameters. + +Browse datasets +Explore feature sets +Choose an architecture + +## Tutorials and experiments + +Train a sleep-detection model from wrist IMU data in the saved notebook, or explore how feature and model choices affect sleep staging. + +Detection training notebook +Staging ablation study diff --git a/docs/guides/stage-ablation.md b/astro-site/src/content/docs/guides/stage-ablation.mdx similarity index 81% rename from docs/guides/stage-ablation.md rename to astro-site/src/content/docs/guides/stage-ablation.mdx index 2ffa5c9..a158186 100644 --- a/docs/guides/stage-ablation.md +++ b/astro-site/src/content/docs/guides/stage-ablation.mdx @@ -1,5 +1,7 @@ -# Sleep Staging Ablation Studies - +--- +title: "Sleep Staging Ablation Studies" +description: "In the following, we perform ablation studies to investigate the impact of different design choices on the performance of the model. All ablation studies are…" +--- ## Overview @@ -12,7 +14,7 @@ We first evaluate the impact of the temporal context- the number of time steps t A typical night sleep involves 4 or 5 sleep cycles each of which lasts around 90-120 minutes. By providing the model with nearly an entire cycle allows the model to learn the patterns associated with each stage. However, providing the model with more than one cycle does not provide additional benefit. This is likely due to the fact that the model is already able to learn the patterns associated with each stage within a single cycle.
---8<-- "assets/guides/stage/ablation-temporal.html"
+
---
@@ -22,7 +24,7 @@ A typical night sleep involves 4 or 5 sleep cycles each of which lasts around 90
Another important design choice is the width (aka. # channels) of the network. To reduce the number of hyper-parameters, we provide a width multiplier to adjust number of channels in each layer relative to the baseline model. For example, a width multiplier of 0.5 means that the number of channels in each layer is half of the baseline model. The following plot shows the impact of the width multiplier on the validation loss. Increasing the width to 1.25 provides a slight 1.2% reduction in loss but requires 47% more FLOPS. As we continue to increase the width, the loss largely plateaus while the FLOPS and memory requirements increase dramatically. On the other hand, decreasing the width below 1 causes a stark increase in loss.
---8<-- "assets/guides/stage/ablation-width.html"
+
---
@@ -32,7 +34,7 @@ Another important design choice is the width (aka. # channels) of the network. T
We further investigate the impact on kernel size on the validation loss. Traditionally, computer vision tasks leveraged 3x3 filter sizes. However, recent works have shown that larger filter sizes can provide better performance especially in 1D time-series by providing larger receptive fields. The plot below shows the impact of the kernel size on the validation loss. Using a filter length of 5 provides a significant reduction in loss while requiring 10% increase in FLOPS and 1K additional parameters. Beyond a filter length of 5, the loss plateaus while the FLOPS and memory requirements increase.
---8<-- "assets/guides/stage/ablation-kernelsize.html"
+
---
@@ -42,7 +44,7 @@ We further investigate the impact on kernel size on the validation loss. Traditi
In the following ablation, we evaluate the impact of the squeeze-and-excitation (SE) ratio. As background, the SE block "adaptively recalibrates channel-wise feature responses by explicitly modelling interdependencies between channels." The SE reduction ratio is a hyperparameter that controls the amount channel compression within the SE block. When the SE block is utilized, the reduction ratio has negligible impact on the computational and memory cost. The following plot shows the impact on validation loss for different SE reduction ratios. NOTE: `ratio=0` corresponds to no SE block. We see that using an SE ratio of 4 results in the lowest validation loss. This provides a 16% reduction in loss while requiring only 3K additional parameters versus no SE blocks.
---8<-- "assets/guides/stage/ablation-se-ratio.html"
+
---
@@ -51,9 +53,8 @@ In the following ablation, we evaluate the impact of the squeeze-and-excitation
Taking inspiration from WaveNet, we evaluate the impact of dilated convolutions on the validation loss. By utilizing increasing dilation rates, we are able to increase the temporal context without increasing the number of parameters nor computation. For example, using a dilation rate of 4 with a kernel length of 5 gives a temporal resolution of 20 time steps compared to 5 time steps for a standard convolution. The following bar chart shows the impact of using dilation convolutions on the validation loss. In the case with dilation, dilation rates of 1, 2, 4, and 8 are used. By adding dilation the model loss decreases by 23% without any increase on memory or computation footprint.
-
---8<-- "assets/guides/stage/ablation-dilation.html"
+
---
diff --git a/docs/huggingface-artifacts.md b/astro-site/src/content/docs/huggingface-artifacts.mdx
similarity index 94%
rename from docs/huggingface-artifacts.md
rename to astro-site/src/content/docs/huggingface-artifacts.mdx
index 1875ed5..e7e26ce 100644
--- a/docs/huggingface-artifacts.md
+++ b/astro-site/src/content/docs/huggingface-artifacts.mdx
@@ -1,4 +1,7 @@
-# Publish an existing baseline to Hugging Face
+---
+title: "Publish an existing baseline to Hugging Face"
+description: "The additive sleepkit-artifacts CLI packages existing files without training or conversion. The existing sleepkit CLI is unchanged. The first reviewed adapter…"
+---
The additive `sleepkit-artifacts` CLI packages existing files without training or
conversion. The existing `sleepkit` CLI is unchanged. The first reviewed adapter
@@ -19,7 +22,7 @@ does not change those dependencies or upgrade TensorFlow.
For optional synthetic runtime checks in a separate environment:
-```sh
+```sh title="Terminal"
python -m venv /tmp/sleepkit-artifacts-env
. /tmp/sleepkit-artifacts-env/bin/activate
python -m pip install 'numpy>=2.1,<3' 'ai-edge-litert>=2.2,<3'
@@ -29,7 +32,7 @@ Obtain the three historical source files (the adapter verifies their pinned
SHA-256 hashes before staging). Source files and generated bundles belong outside
the repository:
-```sh
+```sh title="Terminal"
mkdir -p /tmp/sd-2-source
for file in model.tflite metrics.json configuration.json; do
curl --fail --location \
@@ -76,10 +79,10 @@ These issues are documented in the model card and remain open for the next recip
## Stage a licensed release from an experiment
-Once the [per-model license decision](model-licensing-policy.md) is established,
+Once the [per-model license decision](/sleepkit/model-licensing-policy/) is established,
promote the verified experiment into a new release directory:
-```sh
+```sh title="Terminal"
python -m sleepkit.artifacts stage-release /path/to/experiment/bundle /path/to/release \
--license-file /path/to/chosen/LICENSE --license-id bsd-3-clause \
--card-body /path/to/release-card.md --decision-file /path/to/release-decision.md \
@@ -114,7 +117,7 @@ maintainer's decision; the tool cannot establish rights or approve publication.
The same operation is available as ordinary Python:
-```python
+```python title="Python example"
from pathlib import Path
from sleepkit.artifacts import stage_release
@@ -150,7 +153,7 @@ or supply `--license-file PATH` and `--license-id HF_LICENSE_ID` when staging a
historical baseline. Include required attribution and retain upstream notices. Then install `huggingface-hub>=1,<2`,
authenticate using its standard token mechanism, and explicitly invoke:
-```sh
+```sh title="Terminal"
python -m sleepkit.artifacts publish /tmp/licensed-sd-2-bundle \
AmbiqAI/sleepkit-sd-2-tcn-sm --profile runnable --upload
```
@@ -164,7 +167,7 @@ it does not provision a hosted inference endpoint.
Use the returned immutable revision for download and verification:
-```python
+```python title="Python example"
import shutil
from sleepkit.artifacts.hub import download_bundle
from sleepkit.artifacts.runtime import replay_bundle
@@ -187,7 +190,7 @@ card conventions.
## Reuse from future recipes
-```python
+```python title="Python example"
from pathlib import Path
from sleepkit.artifacts import Artifact, TensorSpec, stage_bundle
@@ -214,7 +217,7 @@ The native Python detection recipe now integrates preprocessing, training, evalu
and export. Next, exercise a deliberately different recipe before promoting shared
blocks into a broader API; keep the legacy CLI available during this migration.
-The [membership int8 release preparation](detection-int8.md) now stages a new-model
+The [membership int8 release preparation](/sleepkit/detection-int8/) now stages a new-model
bundle with preserved float/checkpoint artifacts, train-only calibration evidence,
matched evaluation, and supported raw-sensor inference for both TFLite models.
It can be validated and inspected through the same Hub dry-run interface. Model
diff --git a/docs/index.md b/astro-site/src/content/docs/index.mdx
similarity index 54%
rename from docs/index.md
rename to astro-site/src/content/docs/index.mdx
index 9ee6a2d..263d595 100644
--- a/docs/index.md
+++ b/astro-site/src/content/docs/index.mdx
@@ -1,10 +1,11 @@
-# From sleep signals to Edge AI
-
-
+---
+title: "From sleep signals to Edge AI"
+description: "AI development kit for sleep monitoring on Ambiq devices."
+hero:
+ tagline: "sleepKIT is a Python development kit for building sleep-monitoring AI for Ambiq devices. Turn sensor recordings into features, train and evaluate models, and prepare them for deployment at the edge."
+---
-sleepKIT is a Python development kit for building sleep-monitoring AI for Ambiq devices. Turn sensor recordings into features, train and evaluate models, and prepare them for deployment at the edge.
-
-
+import { Tabs, TabItem } from '@astrojs/starlight/components';
## A starting point for your sleep-monitoring application
@@ -39,7 +40,7 @@ Start with a built-in task, or extend the same workflow with your own training,
+ 
+ 
+