### Install SleepECG with full dependencies

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/index.md

Installs the package along with all optional dependencies.

```bash
pip install "sleepecg[full]"
```

--------------------------------

### Install Benchmark Requirements

Source: https://github.com/cbrnr/sleepecg/blob/main/examples/benchmark/README.md

Installs necessary packages for running the benchmark. Ensure you are in a virtual environment.

```bash
pip install -r requirements-benchmark.txt
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Install pre-commit hooks locally to ensure staged files pass style and quality checks before committing.

```bash
pre-commit install
```

--------------------------------

### Install SleepECG development version

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/index.md

Installs the latest version directly from the GitHub repository.

```bash
pip install git+https://github.com/cbrnr/sleepecg
```

--------------------------------

### Install SleepECG via pip

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/index.md

Standard installation command for the SleepECG package.

```bash
pip install sleepecg
```

--------------------------------

### Install SleepECG with development dependencies

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Install SleepECG in editable mode with all development dependencies required for style checking, testing, and documentation.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Get All Configuration

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/configuration.md

Retrieves all current configuration settings for Sleepecg.

```APIDOC
## GET /config

### Description
Retrieves all current configuration settings for Sleepecg.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **config_data** (object) - A JSON object containing all configuration key-value pairs.

#### Response Example
```json
{
  "setting1": "value1",
  "setting2": 123
}
```
```

--------------------------------

### Install SleepECG

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Commands for installing the package via pip, including optional dependencies and development versions.

```bash
# Basic installation
pip install sleepecg

# Full installation with all optional dependencies
pip install "sleepecg[full]"

# Development version
pip install git+https://github.com/cbrnr/sleepecg
```

--------------------------------

### Save Classifier Example

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/classification.md

Illustrates how to save a trained classifier using the `save_classifier` function. This is required when contributing new classifiers to SleepECG.

```python
sleepecg.save_classifier(classifier, 'my-classifier.zip')
```

--------------------------------

### Get Specific Configuration Value

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/configuration.md

Retrieves the value of a specific configuration setting.

```APIDOC
## GET /config/{key}

### Description
Retrieves the value of a specific configuration setting identified by its key.

### Method
GET

### Endpoint
/config/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the configuration setting to retrieve.

### Response
#### Success Response (200)
- **value** (string | number | boolean) - The value of the requested configuration setting.

#### Response Example
```json
{
  "value": "some_value"
}
```
```

--------------------------------

### Load Toy ECG Data and Detect Heartbeats

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/heartbeat_detection.md

Loads a sample ECG signal and its sampling frequency, then detects heartbeats. This is useful for testing and examples.

```python
import numpy as np
from sleepecg import detect_heartbeats, get_toy_ecg

ecg, fs = get_toy_ecg()  # 5 min of ECG data at 360 Hz
beats = detect_heartbeats(ecg, fs)
```

--------------------------------

### Execute Complete Training Pipeline

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Demonstrates the full workflow from data loading and feature extraction to model training and evaluation.

```python
import warnings
from tqdm import tqdm
from tensorflow.keras import layers, models
from sleepecg import (
    evaluate,
    extract_features,
    load_classifier,
    prepare_data_keras,
    print_class_balance,
    read_mesa,
    read_shhs,
    save_classifier,
    set_nsrr_token,
)

set_nsrr_token("your-token-here")

# Suppress expected warnings during feature extraction
warnings.filterwarnings("ignore", category=RuntimeWarning, message="HR analysis window too short")

# Define feature extraction parameters
feature_extraction_params = {
    "lookback": 240,
    "lookforward": 270,
    "feature_selection": ["hrv-time", "hrv-frequency", "recording_start_time", "age", "gender"],
    "min_rri": 0.3,
    "max_rri": 2,
    "max_nans": 0.5,
}

# Load training data (MESA dataset)
print("Loading training data...")
train_records = list(read_mesa(offline=False))

# Extract features
print("Extracting features...")
features_train, stages_train, feature_ids = extract_features(
    tqdm(train_records),
    **feature_extraction_params,
    n_jobs=-1,
)

# Prepare for Keras
stages_mode = "wake-sleep"
features_pad, stages_onehot, sample_weights = prepare_data_keras(
    features_train, stages_train, stages_mode
)
print_class_balance(stages_onehot, stages_mode)

# Build model
model = models.Sequential([
    layers.Input((None, features_pad.shape[2])),
    layers.Masking(-1),
    layers.BatchNormalization(),
    layers.Dense(64),
    layers.ReLU(),
    layers.Bidirectional(layers.GRU(8, return_sequences=True)),
    layers.Bidirectional(layers.GRU(8, return_sequences=True)),
    layers.Dense(stages_onehot.shape[-1], activation="softmax"),
])

model.compile(optimizer="rmsprop", loss="categorical_crossentropy", metrics=["accuracy"])

# Train
print("Training model...")
model.fit(features_pad, stages_onehot, epochs=5, sample_weight=sample_weights)

# Save classifier
save_classifier(
    name="ws-gru-custom",
    model=model,
    stages_mode=stages_mode,
    feature_extraction_params=feature_extraction_params,
    mask_value=-1,
    classifiers_dir="./classifiers",
)

# Evaluate on test data (SHHS dataset)
print("Evaluating on test data...")
clf = load_classifier("ws-gru-custom", "./classifiers")
test_records = list(read_shhs(offline=False))

features_test, stages_test, _ = extract_features(
    tqdm(test_records),
    **clf.feature_extraction_params,
    n_jobs=-1,
)

features_test_pad, stages_test_pad, _ = prepare_data_keras(
    features_test, stages_test, clf.stages_mode
)

y_pred = clf.model.predict(features_test_pad)
evaluate(stages_test_pad, y_pred, clf.stages_mode)
```

--------------------------------

### List and Load Classifiers

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Displays available pre-trained classifiers bundled with the library.

```python
from sleepecg import load_classifier, list_classifiers

# List available bundled classifiers
list_classifiers("SleepECG")
```

--------------------------------

### Download NSRR Data Files

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Downloads raw files from NSRR datasets for manual management.

```python
from sleepecg import download_nsrr, set_nsrr_token

set_nsrr_token("<your-download-token-here>")

# Download EDF files from MESA
download_nsrr(
    db_slug="mesa",
    subfolder="polysomnography/edfs",
    pattern="*-00*",           # Records 0001-0099
    data_dir="./datasets",     # Local directory
)

# Download annotation files
download_nsrr(
    db_slug="mesa",
    subfolder="polysomnography/annotations-events-nsrr",
    pattern="*-00*-nsrr.xml",
    data_dir="./datasets",
)
```

--------------------------------

### Run Heartbeat Detection Benchmark

Source: https://github.com/cbrnr/sleepecg/blob/main/examples/benchmark/README.md

Executes the heartbeat detection benchmark. An optional argument specifies the benchmark type (e.g., runtime, metrics, rri_similarity). Defaults to 'runtime'.

```bash
python benchmark_detectors.py [<benchmark>]
```

--------------------------------

### Clone the SleepECG repository

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Clone the forked repository to your local machine to begin development.

```bash
git clone https://github.com/<your-username>/sleepecg
```

--------------------------------

### Download NSRR Data Files

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/datasets.md

Downloads specified files from an NSRR dataset to a local directory. Requires setting an NSRR token. Subfolders are created to preserve the original directory structure.

```python
from sleepecg import download_nsrr, set_nsrr_token

set_nsrr_token("<your-download-token-here>")
download_nsrr(
    db_slug="mesa",
    subfolder="polysomnography/edfs",
    pattern="*-00*",
    data_dir="./datasets",
)
```

--------------------------------

### Parameter Documentation Template

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/templates/python/material/docstring/parameters.html

This template defines how parameter lists are rendered in the documentation, including support for parameter names, type annotations, and markdown-formatted descriptions.

```APIDOC
## Template: Parameters List

### Description
This template renders a list of parameters for a given section, including the parameter name, type annotation, and description.

### Parameters
- **section.title** (string) - Optional - The title of the parameter section, defaults to "Parameters:"
- **section.value** (list) - Required - A list of parameter objects to be rendered.

### Logic
- Iterates through `section.value`.
- Displays `parameter.name` as code.
- Displays `parameter.annotation` if present.
- Renders `parameter.description` using markdown conversion.
```

--------------------------------

### Prepare Data for Keras Models

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Prepares feature matrices and sleep stage labels for training Keras models. Handles masking, padding, one-hot encoding, and sample weight calculation. Requires extracted features and stages as input.

```python
import numpy as np
from sleepecg import prepare_data_keras, extract_features, read_slpdb

# Extract features from records
records = list(read_slpdb("*41*"))
features, stages, feature_ids = extract_features(
    records,
    feature_selection=["hrv-time"],
    lookback=60,
    lookforward=30,
)

# Prepare data for Keras
features_pad, stages_onehot, sample_weights = prepare_data_keras(
    features,
    stages,
    stages_mode="wake-sleep",
    mask_value=-1,
)

print(f"Features shape: {features_pad.shape}")      # (n_records, max_epochs, n_features)
print(f"Stages shape: {stages_onehot.shape}")       # (n_records, max_epochs, n_classes+1)
print(f"Sample weights shape: {sample_weights.shape}")  # (n_records, max_epochs)

# Build and train a Keras model
from tensorflow.keras import layers, models

model = models.Sequential([
    layers.Input((None, features_pad.shape[2])),
    layers.Masking(-1),
    layers.BatchNormalization(),
    layers.Dense(64, activation="relu"),
    layers.Bidirectional(layers.GRU(8, return_sequences=True)),
    layers.Dense(stages_onehot.shape[-1], activation="softmax"),
])

model.compile(optimizer="adam", loss="categorical_crossentropy", metrics=["accuracy"])
model.fit(features_pad, stages_onehot, epochs=5, sample_weight=sample_weights)
```

--------------------------------

### Detect heartbeats in ECG data

Source: https://github.com/cbrnr/sleepecg/blob/main/README.md

Demonstrates heartbeat detection using a toy ECG dataset.

```python
import numpy as np
from sleepecg import detect_heartbeats, get_toy_ecg

ecg, fs = get_toy_ecg()  # 5 min of ECG data at 360 Hz
beats = detect_heartbeats(ecg, fs)  # indices of detected heartbeats
```

--------------------------------

### Run tests excluding C extensions

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Run the test suite while skipping tests marked with the c_extension marker.

```bash
pytest -m "not c_extension"
```

--------------------------------

### Load and Inspect a Classifier

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Loads a pre-trained classifier and accesses its attributes. Ensure the classifier name and directory are correct.

```python
clf = load_classifier("ws-gru-mesa", "SleepECG")

print(clf)
# SleepClassifier for WAKE-SLEEP
#     features: meanNN, maxNN, minNN, ...
#     model type: keras
#     source file: ws-gru-mesa.zip

# Access classifier attributes
print(f"Stages mode: {clf.stages_mode}")
print(f"Model type: {clf.model_type}")
print(f"Mask value: {clf.mask_value}")
print(f"Feature params: {clf.feature_extraction_params}")
```

```python
# Load from custom directory
custom_clf = load_classifier("my-classifier", "./classifiers")
```

--------------------------------

### Set Configuration Value

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/configuration.md

Sets or updates a specific configuration setting.

```APIDOC
## POST /config

### Description
Sets or updates a specific configuration setting.

### Method
POST

### Endpoint
/config

### Parameters
#### Request Body
- **key** (string) - Required - The key of the configuration setting to set.
- **value** (string | number | boolean) - Required - The value to set for the configuration setting.

### Request Example
```json
{
  "key": "new_setting",
  "value": "new_value"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the setting was updated.

#### Response Example
```json
{
  "message": "Configuration 'new_setting' updated successfully."
}
```
```

--------------------------------

### Yields Documentation Pattern

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/templates/python/material/docstring/yields.html

Describes the standard format for documenting generator yields in the SleepECG project.

```APIDOC
## Yields Documentation Pattern

### Description
This template defines how generator yields are documented in the project, including support for names, type annotations, and descriptions.

### Parameters
#### Yields
- **name** (string) - Optional - The name of the yielded value.
- **annotation** (expression) - Optional - The type annotation or expression associated with the yielded value.
- **description** (string) - Required - A markdown-formatted description of the yielded value.
```

--------------------------------

### Run project tests

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Execute all tests within the project or package root using pytest.

```bash
pytest
```

--------------------------------

### Data Export and Configuration

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/datasets.md

Functions for exporting records and configuring access tokens.

```APIDOC
## sleepecg.export_ecg_record
### Description
Exports an ECG record to a specified format.

## sleepecg.set_nsrr_token
### Description
Sets the authentication token required for accessing NSRR datasets.
```

--------------------------------

### Use WAKE-SLEEP Classifier

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/classification.md

Demonstrates how to use the 'ws-gru-mesa' classifier for WAKE-SLEEP stage classification. This classifier is based on a GRU model trained on the MESA dataset.

```python
import sleepecg

# Load the WAKE-SLEEP classifier
classifier = sleepecg.load_classifier('ws-gru-mesa')

# Example usage (assuming 'record' is a loaded sleep recording)
# stages = classifier.predict(record)

```

--------------------------------

### Configuration Management API

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/configuration.md

Manage global configuration settings for SleepECG. This includes retrieving current settings and updating them.

```APIDOC
## Configuration Management

SleepECG provides an interface to set and persist global configuration values.

### Functions

- `get_config()`: Retrieves all current configuration settings.
- `get_config_value(key)`: Retrieves the value of a specific configuration key.
- `set_config(key, value)`: Sets a specific configuration key to a new value.

### Configuration Settings

| Key               | Default value               | Description                                                                                                | Used in |
| ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `data_dir`        | `'~/.sleepecg/datasets'`    | Default location for storing files downloaded by reader functions, including data downloaded for tests. | [`read_ltdb()`, `read_mitdb()`, `read_gudb()`, `read_mesa()`, `read_shhs()`, `read_slpdb()`] |
| `classifiers_dir` | `'~/.sleepecg/classifiers'` | Default location for `SleepClassifier` objects.                                                              | [`list_classifiers()`, `load_classifier()`, `save_classifier()`] |

### Example Usage

```python
import sleepecg

# Get all configurations
config = sleepecg.get_config()
print(config)

# Get a specific configuration value
data_directory = sleepecg.get_config_value('data_dir')
print(f"Data directory: {data_directory}")

# Set a configuration value
sleepecg.set_config('data_dir', '/path/to/new/data')
new_data_directory = sleepecg.get_config_value('data_dir')
print(f"Updated data directory: {new_data_directory}")
```
```

--------------------------------

### download_nsrr

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Downloads files from NSRR datasets without processing them.

```APIDOC
## download_nsrr

### Description
Downloads files from NSRR datasets without processing them. Useful for manual data management or downloading specific subsets.

### Parameters
#### Query Parameters
- **db_slug** (str) - Required - The database identifier.
- **subfolder** (str) - Required - The subfolder path within the dataset.
- **pattern** (str) - Optional - File pattern to match.
- **data_dir** (str) - Optional - Local directory for storage.
```

--------------------------------

### Read MESA Dataset Records

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Loads MESA sleep data. Requires an NSRR authentication token for access.

```python
from sleepecg import read_mesa, set_nsrr_token

# Set NSRR authentication token (get from https://sleepdata.org/token)
set_nsrr_token("<your-download-token-here>")

# Read all MESA records (generator)
mesa_records = read_mesa()

# Read subset of records
mesa_subset = read_mesa(records_pattern="00*")  # Records 0001-0099

# Different heartbeat sources
mesa_annotated = read_mesa(heartbeats_source="annotation")  # Use R-peak annotations
mesa_detected = read_mesa(heartbeats_source="ecg")          # Detect from ECG
mesa_cached = read_mesa(heartbeats_source="cached")         # Use cached detections

# Include actigraphy data
mesa_with_activity = read_mesa(activity_source="actigraphy")

# Offline mode (use local files only)
mesa_offline = read_mesa(offline=True)

# Process records
for record in read_mesa(records_pattern="0001"):
    print(f"Record: {record.id}")
    print(f"Sleep stages: {record.sleep_stages[:10]}")
    print(f"Heartbeat times: {record.heartbeat_times[:5]}")
```

--------------------------------

### Manage SleepECG Configuration

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Functions to retrieve and update global configuration settings, such as data and classifier directories.

```python
from sleepecg import get_config, get_config_value, set_config

# Get all configuration values
config = get_config()
print(config)
# {'data_dir': '~/.sleepecg/datasets', 'classifiers_dir': '~/.sleepecg/classifiers'}

# Get specific configuration value
data_dir = get_config_value("data_dir")
print(f"Data directory: {data_dir}")

# Set configuration values (persisted to ~/.sleepecg/config.yml)
set_config(data_dir="/path/to/datasets")
set_config(classifiers_dir="/path/to/classifiers")

# Remove a configuration key (reverts to default)
set_config(data_dir=None)
```

--------------------------------

### Extract Features from Sleep Data

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/examples.md

Generates dummy sleep data and extracts features like HRV, LF/HF ratio, and normalized LF/HF power. Requires numpy.

```python
import numpy as np

from sleepecg import SleepRecord, extract_features

# generate dummy data
recording_hours = 8
heartbeat_times = np.cumsum(np.random.uniform(0.5, 1.5, recording_hours * 3600))
sleep_stages = np.random.randint(1, 6, int(max(heartbeat_times)) // 30)
sleep_stage_duration = 30

record = SleepRecord(
    sleep_stages=sleep_stages,
    sleep_stage_duration=sleep_stage_duration,
    heartbeat_times=heartbeat_times,
)

features, stages, feature_ids = extract_features(
    [record],
    lookback=240,
    lookforward=60,
    feature_selection=["hrv-time", "LF_norm", "HF_norm", "LF_HF_ratio"],
)
X = features[0]
```

--------------------------------

### Compare Heartbeats

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Evaluates heartbeat detector performance by comparing detected beats against ground truth annotations.

```python
import numpy as np
from sleepecg import compare_heartbeats, detect_heartbeats, get_toy_ecg

ecg, fs = get_toy_ecg()
beats = detect_heartbeats(ecg, fs)

# Add noise and detect again
np.random.seed(42)
ecg_noisy = ecg + np.random.rand(ecg.size)
beats_noisy = detect_heartbeats(ecg_noisy, fs)

# Compare with 100ms tolerance (36 samples at 360 Hz)
tp, fp, fn = compare_heartbeats(beats_noisy, beats, max_distance=36)

# Calculate metrics
precision = len(tp) / (len(tp) + len(fp)) if (len(tp) + len(fp)) > 0 else 0
recall = len(tp) / (len(tp) + len(fn)) if (len(tp) + len(fn)) > 0 else 0
f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0

print(f"True Positives: {len(tp)}")
print(f"False Positives: {len(fp)}")
print(f"False Negatives: {len(fn)}")
print(f"Precision: {precision:.4f}, Recall: {recall:.4f}, F1: {f1:.4f}")
```

--------------------------------

### Plot Benchmark Results

Source: https://github.com/cbrnr/sleepecg/blob/main/examples/benchmark/README.md

Generates plots from benchmark results. The output filename determines plot type and labels. Ensure the input CSV file exists.

```bash
python plot_benchmark_results.py <results.csv>
```

--------------------------------

### Add upstream remote for SleepECG

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Add the original SleepECG repository as a remote named 'upstream' to your local clone for fetching updates.

```bash
git remote add upstream git@github.com:cbrnr/sleepecg.git
```

--------------------------------

### compare_heartbeats

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Compares detected heartbeats against ground truth annotations to compute true positives, false positives, and false negatives.

```APIDOC
## compare_heartbeats

### Description
Compares detected heartbeats against ground truth annotations to compute true positives, false positives, and false negatives. Useful for evaluating heartbeat detector performance with a configurable tolerance window.

### Parameters
#### Arguments
- **detected** (array) - Required - Indices of detected heartbeats.
- **annotated** (array) - Required - Indices of ground truth heartbeats.
- **max_distance** (int) - Optional - Maximum distance in samples to consider a heartbeat as a match.

### Response
- **tp** (array) - Indices of true positive detections.
- **fp** (array) - Indices of false positive detections.
- **fn** (array) - Indices of false negative detections.
```

--------------------------------

### Sleep Staging with Custom EDF Data

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/examples.md

Loads ECG data from an EDF file, detects heartbeats, and predicts sleep stages using a pre-trained classifier. Requires edfio and tensorflow. Ensure 'sleep.edf' is in the working directory.

```python
from datetime import datetime

from edfio import read_edf

import sleepecg

# load dataset

edf = read_edf("sleep.edf")

# crop dataset (we only want data for the sleep duration)
start = datetime(2023, 3, 1, 23, 0, 0)
stop = datetime(2023, 3, 2, 6, 0, 0)
rec_start = datetime.combine(edf.startdate, edf.starttime)
edf.slice_between_seconds((start - rec_start).seconds, (stop - rec_start).seconds)

# get ECG time series and sampling frequency
ecg = edf.get_signal("ECG").data
fs = edf.get_signal("ECG").sampling_frequency

# detect heartbeats
beats = sleepecg.detect_heartbeats(ecg, fs)
sleepecg.plot_ecg(ecg, fs, beats=beats)

# load SleepECG classifier (requires tensorflow)
clf = sleepecg.load_classifier("wrn-gru-mesa", "SleepECG")

# predict sleep stages
record = sleepecg.SleepRecord(
    sleep_stage_duration=30,
    recording_start_time=start,
    heartbeat_times=beats / fs,
)

stages = sleepecg.stage(clf, record, return_mode="prob")

sleepecg.plot_hypnogram(
    record,
    stages,
    stages_mode=clf.stages_mode,
    merge_annotations=True,
)
```

--------------------------------

### Save a Trained Classifier

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Saves a trained classifier and its metadata to a zip file for later use. Requires the trained model, name, and feature extraction parameters.

```python
from sleepecg import save_classifier

# After training a Keras model...
feature_extraction_params = {
    "lookback": 240,
    "lookforward": 270,
    "feature_selection": ["hrv-time", "hrv-frequency", "age", "gender"],
    "min_rri": 0.3,
    "max_rri": 2,
    "max_nans": 0.5,
}

save_classifier(
    name="my-sleep-classifier",
    model=model,
    stages_mode="wake-sleep",
    feature_extraction_params=feature_extraction_params,
    mask_value=-1,
    classifiers_dir="./classifiers",
)

# Creates: ./classifiers/my-sleep-classifier.zip
# Contains: classifier.keras, info.yml

```

--------------------------------

### Detect and Visualize Heartbeats

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/examples.md

Detects heartbeats from ECG data and visualizes the raw ECG, detected events, and calculated heart rate. Requires matplotlib and numpy.

```python
import matplotlib.pyplot as plt
import numpy as np

from sleepecg import compare_heartbeats, detect_heartbeats, read_mitdb

# download and read data
record = list(read_mitdb(records_pattern="234"))[1]

# detect heartbeats
detection = detect_heartbeats(record.ecg, record.fs)

# evaluation and visualization
TP, FP, FN = compare_heartbeats(detection, record.annotation, int(record.fs / 10))

t = np.arange(len(record.ecg)) / record.fs

fig, ax = plt.subplots(3, sharex=True, figsize=(10, 8))

ax[0].plot(t, record.ecg, color="k", zorder=1, label="ECG")
ax[0].scatter(
    record.annotation / record.fs,
    record.ecg[record.annotation],
    marker="o",
    color="g",
    s=50,
    zorder=2,
    label="annotation",
)
ax[0].set_ylabel("raw signal in mV")

ax[1].eventplot(
    detection / record.fs,
    linelength=0.5,
    linewidth=0.5,
    color="k",
    zorder=1,
    label="detection",
)
ax[1].scatter(
    FN / record.fs,
    np.ones_like(FN),
    marker="x",
    color="r",
    s=70,
    zorder=2,
    label="FN",
)
ax[1].scatter(
    FP / record.fs,
    np.ones_like(FP),
    marker="+",
    color="orange",
    s=70,
    zorder=2,
    label="FP",
)
ax[1].set_yticks([])
ax[1].set_ylabel("heartbeat events")

ax[2].plot(
    detection[1:] / record.fs,
    60 / (np.diff(detection) / record.fs),
    label="heartrate in bpm",
)
ax[2].set_ylabel("beats per minute")
ax[2].set_xlabel("time in seconds")

for ax_ in ax.flat:
    ax_.legend(loc="upper right")
    ax_.grid(axis="x")

fig.suptitle(
    f"Record ID: {record.id}, lead: {record.lead}
" \
    + f"Recall: {len(TP) / (len(TP) + len(FN)):.2%}, "
    + f"Precision: {len(TP) / (len(TP) + len(FP)):.2%}"
)

plt.show()
```

--------------------------------

### SleepECG file header

Source: https://github.com/cbrnr/sleepecg/blob/main/CONTRIBUTING.md

Each source file in SleepECG must include this header, specifying copyright and license information.

```python
# © SleepECG developers
#
# License: BSD (3-clause)

```

--------------------------------

### Classification Module API

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/classification.md

Overview of the available functions and classes for classifier management and data preparation.

```APIDOC
## Classification Functions and Classes

### Description
This module provides tools for evaluating, listing, loading, saving, and staging sleep ECG classifiers, as well as preparing data for Keras models.

### Available Components
- **sleepecg.evaluate**: Evaluates the performance of a classifier.
- **sleepecg.list_classifiers**: Lists all available classifiers.
- **sleepecg.load_classifier**: Loads a pre-trained classifier from storage.
- **sleepecg.prepare_data_keras**: Prepares data specifically for Keras-based models.
- **sleepecg.print_class_balance**: Prints the distribution of classes in the dataset.
- **sleepecg.save_classifier**: Saves a trained classifier to storage.
- **sleepecg.stage**: Handles staging operations for classification.
- **sleepecg.SleepClassifier**: The primary class for implementing sleep ECG classification.
```

--------------------------------

### Data Retrieval Functions

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/datasets.md

Functions for downloading and reading various ECG and sleep datasets.

```APIDOC
## sleepecg.download_nsrr
### Description
Downloads data from the National Sleep Research Resource (NSRR).

## sleepecg.download_physionet
### Description
Downloads data from PhysioNet.

## sleepecg.read_gudb
### Description
Reads the GUDB dataset.

## sleepecg.read_ltdb
### Description
Reads the Long-Term ST Database (LTDB).

## sleepecg.read_mesa
### Description
Reads the MESA dataset.

## sleepecg.read_mitdb
### Description
Reads the MIT-BIH Arrhythmia Database (MITDB).

## sleepecg.read_shhs
### Description
Reads the Sleep Heart Health Study (SHHS) dataset.

## sleepecg.read_slpdb
### Description
Reads the Sleep-EDF Database (SLPDB).
```

--------------------------------

### Read SLPDB Records

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Accesses the MIT-BIH Polysomnographic Database. Automatically handles downloads unless offline mode is specified.

```python
from sleepecg import read_slpdb

# Read all records (downloads data automatically)
all_records = list(read_slpdb())

# Read specific records by pattern
selected_records = list(read_slpdb(records_pattern="slp41"))

# Read records in offline mode (no download)
offline_records = list(read_slpdb(offline=True))

# Access record data
for record in read_slpdb("*41*"):
    print(f"Record ID: {record.id}")
    print(f"Sleep stages: {len(record.sleep_stages)} epochs")
    print(f"Stage duration: {record.sleep_stage_duration}s")
    print(f"Heartbeats: {len(record.heartbeat_times)}")
    print(f"Subject age: {record.subject_data.age}")
    print(f"Subject weight: {record.subject_data.weight}")
    print(f"Recording start: {record.recording_start_time}")
```

--------------------------------

### Heartbeat Detection and Analysis

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/api/heartbeat_detection.md

Functions for processing ECG data, detecting heartbeats, and performing similarity analysis.

```APIDOC
## sleepecg.compare_heartbeats

### Description
Compares two sets of heartbeat annotations.

## sleepecg.detect_heartbeats

### Description
Detects heartbeats in an ECG signal.

## sleepecg.rri_similarity

### Description
Calculates the similarity between two RRI (R-R interval) series.

## sleepecg.get_toy_ecg

### Description
Retrieves a toy ECG signal for testing purposes.
```

--------------------------------

### Compare Heartbeat Detection with Noise

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/heartbeat_detection.md

Adds random noise to an ECG signal and compares the heartbeat detection results with the original signal. Requires the `compare_heartbeats` function.

```python
import numpy as np
from sleepecg import detect_heartbeats, compare_heartbeats

np.random.seed(42)
ecg_noisy = ecg + np.random.rand(ecg.size)
beats_noisy = detect_heartbeats(ecg_noisy, fs)
tp, fp, fn = compare_heartbeats(beats_noisy, beats)
```

--------------------------------

### Plot ECG with Heartbeat Markers

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Plots ECG time series with optional heartbeat markers. Supports multiple annotation sets with automatic color and marker differentiation. Use 'correct' for detected beats and 'bad' for comparison markers.

```python
import sleepecg

ecg, fs = sleepecg.get_toy_ecg()
beats = sleepecg.detect_heartbeats(ecg[:10 * fs], fs)

# Plot ECG with single annotation set
fig, ax = sleepecg.plot_ecg(ecg[:10 * fs], fs, title="ECG with heartbeats")

# Plot with markers
fig, ax = sleepecg.plot_ecg(
    ecg[:10 * fs],
    fs,
    correct=beats,
    bad=beats + 7,  # Shifted markers for comparison
)

# fig.savefig("ecg_plot.png")

```

--------------------------------

### Evaluate Classifier Performance

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Evaluates classifier performance using true and predicted sleep stages. Prints confusion matrix, accuracy, Cohen's kappa, precision, recall, and F1 scores. Ensure 'stages_mode' matches the classifier's training mode.

```python
import numpy as np
from sleepecg import evaluate

# Simulated true and predicted stages
# Stages: 0=UNDEFINED, 1=SLEEP, 2=WAKE for 'wake-sleep' mode
stages_true = np.array([[0, 1, 1, 1, 2, 2, 1, 1, 2, 1]])
stages_pred = np.array([[0, 1, 1, 2, 2, 2, 1, 1, 1, 1]])

# Evaluate (prints metrics automatically)
conf_mat, stage_names = evaluate(
    stages_true,
    stages_pred,
    stages_mode="wake-sleep",
    show_undefined=False,
)

# Output:
# Confusion matrix (WAKE-SLEEP):
# [[5 1]
#  [1 2]]
# Accuracy: 0.7778
# Cohen's kappa: 0.4706
#        precision    recall  f1-score    support
# SLEEP       0.83      0.83      0.83          6
#  WAKE       0.67      0.67      0.67          3
#                                            9

```

--------------------------------

### Read MESA Dataset Records

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/datasets.md

Reads all records from the MESA dataset. Requires setting an NSRR token beforehand. The reader function returns a generator.

```python
from sleepecg import read_mesa, set_nsrr_token

set_nsrr_token("<your-download-token-here>")
mesa = read_mesa()  # note that this is a generator
```

--------------------------------

### Read Subset of MESA Dataset Records

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/datasets.md

Reads a subset of records from the MESA dataset based on a pattern. Requires setting an NSRR token. The reader function returns a generator.

```python
from sleepecg import read_mesa, set_nsrr_token

set_nsrr_token("<your-download-token-here>")
mesa = read_mesa(records_pattern="00*")  # note that this is a generator
```

--------------------------------

### Read SHHS Dataset Records

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Loads SHHS records. Requires NSRR authentication.

```python
from sleepecg import read_shhs, set_nsrr_token

set_nsrr_token("<your-download-token-here>")

# Read SHHS records
shhs_records = read_shhs()

# Read specific subset
shhs_subset = read_shhs(records_pattern="shhs1-200*")

# Different options
shhs_from_ecg = read_shhs(heartbeats_source="ecg", keep_edfs=False)

for record in read_shhs(records_pattern="shhs1-200001"):
    print(f"Record: {record.id}")
    print(f"Age: {record.subject_data.age}")
    print(f"Gender: {record.subject_data.gender}")
```

--------------------------------

### Calculate RRI Similarity

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Computes similarity metrics between two RR interval time series to assess detection accuracy.

```python
import numpy as np
from sleepecg import rri_similarity, detect_heartbeats, get_toy_ecg

ecg, fs = get_toy_ecg()
detected = detect_heartbeats(ecg, fs)

# Simulate annotated heartbeats (slightly different positions)
np.random.seed(42)
annotated = detected + np.random.randint(-5, 6, len(detected))
annotated = np.sort(annotated)

# Calculate RRI similarity metrics
pearsonr, spearmanr, rmse = rri_similarity(detected, annotated, fs_resample=4)

print(f"Pearson correlation: {pearsonr:.4f}")
print(f"Spearman correlation: {spearmanr:.4f}")
print(f"RMSE: {rmse:.4f}")
```

--------------------------------

### Visualize Hypnograms with SleepECG

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Generates a hypnogram plot from a record, allowing for the visualization of sleep stages and heart rate data.

```python
import sleepecg

# Read a record
record = next(sleepecg.read_slpdb("*41*"))

# Plot hypnogram (using annotations as "predictions" for demo)
fig, axes = sleepecg.plot_hypnogram(
    record,
    stages_pred=record.sleep_stages,
    stages_mode="wake-rem-n1-n2-n3",
    show_bpm=True,
)

# fig.savefig("hypnogram.png")
```

--------------------------------

### Plot ECG Time Course with Annotations

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/plot.md

Plots the time course of an ECG signal with optional annotations like detected heartbeats. Multiple annotations are automatically styled differently. Requires sleepecg and Matplotlib.

```python
import sleepecg

ecg, fs = sleepecg.get_toy_ecg()  # 5 min of ECG data at 360 Hz
beats = sleepecg.detect_heartbeats(ecg[:10 * fs], fs)

sleepecg.plot_ecg(ecg, fs, correct=beats, bad=beats + 7)
```

--------------------------------

### Preprocess RRI

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Cleans RR interval data by masking values outside physiological bounds with NaN.

```python
import numpy as np
from sleepecg import preprocess_rri

# Raw RRI data with some outliers
rri_raw = np.array([0.5, 0.2, 0.8, 2.5, 0.6, 0.1, 1.0, 3.0, 0.7])

# Mask RR intervals outside 0.4-2s range (30-150 bpm)
rri_clean = preprocess_rri(rri_raw, min_rri=0.4, max_rri=2.0)

print("Original RRI:", rri_raw)
print("Cleaned RRI: ", rri_clean)
# Output: [0.5, nan, 0.8, nan, 0.6, nan, 1.0, nan, 0.7]
```

--------------------------------

### Use Built-in Sleep Staging Classifier

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/examples.md

Loads a built-in SleepECG classifier and predicts sleep stages for a record from the SLPDB dataset, then plots the hypnogram. Requires matplotlib.

```python
import matplotlib.pyplot as plt

from sleepecg import load_classifier, plot_hypnogram, read_slpdb, stage

# the model was built with tensorflow 2.16.1, running on higher versions might create
# warnings, but should not influence the results
clf = load_classifier("ws-gru-mesa", "SleepECG")

# load record
# `ws-gru-mesa` performs poorly for most SLPDB records, but it works well for slp03
rec = next(read_slpdb("slp03"))

# predict stages and plot hypnogram
stages_pred = stage(clf, rec, return_mode="prob")

plot_hypnogram(
    rec,
    stages_pred,
    stages_mode=clf.stages_mode,
    merge_annotations=True,
)

plt.show()
```

--------------------------------

### Predict Sleep Stages

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Predicts sleep stages for a given record using a loaded classifier. Handles feature extraction and preprocessing automatically. Can return integer labels, probabilities, or string labels.

```python
from sleepecg import load_classifier, stage, read_slpdb

# Load classifier
clf = load_classifier("ws-gru-mesa", "SleepECG")

# Read a record
record = next(read_slpdb("*41*"))

# Predict sleep stages (returns integer labels)
stages_int = stage(clf, record, return_mode="int")
print(f"Predicted stages (int): {stages_int[:20]}")

# Return probabilities
stages_prob = stage(clf, record, return_mode="prob")
print(f"Probabilities shape: {stages_prob.shape}")
print(f"First epoch probabilities: {stages_prob[0]}")

# Return string labels
stages_str = stage(clf, record, return_mode="str")
print(f"Predicted stages (str): {stages_str[:10]}")
```

--------------------------------

### Extract Features from ECG Records

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Configures parameters for feature extraction and processes records to generate feature matrices and sleep stage labels.

```python
feature_extraction_params = {
    "lookback": 240,          # 4 minutes before each epoch
    "lookforward": 270,       # 4.5 minutes after each epoch
    "sleep_stage_duration": 30,
    "feature_selection": [
        "hrv-time",           # All 26 time-domain features
        "hrv-frequency",      # All 7 frequency-domain features
        "recording_start_time",
        "age",
        "gender",
    ],
    "min_rri": 0.3,           # 200 bpm max heart rate
    "max_rri": 2.0,           # 30 bpm min heart rate
    "max_nans": 0.5,          # Allow up to 50% NaNs in windows
}

# Extract features (can use parallel processing with n_jobs=-1)
features, stages, feature_ids = extract_features(
    records,
    **feature_extraction_params,
    n_jobs=1,
)

# features: list of 2D arrays (n_epochs, n_features) per record
# stages: list of 1D arrays with sleep stage labels per record
# feature_ids: list of feature names matching column order

print(f"Extracted {len(feature_ids)} features: {feature_ids[:5]}...")
print(f"Feature matrix shape: {features[0].shape}")
print(f"Sleep stages shape: {stages[0].shape}")
```

--------------------------------

### Extract HRV Features

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Extracts time and frequency domain HRV features from sleep records.

```python
from sleepecg import extract_features, read_slpdb

# Read records from MIT-BIH Polysomnographic Database
records = list(read_slpdb("*41*"))
```

--------------------------------

### Plot ECG Record Visualization

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/plot.md

Visualizes an ECGRecord object using its plot method. This method can display annotations contained within the record and additional annotations passed as arguments. Requires sleepecg and Matplotlib.

```python
import sleepecg

ecg, fs = sleepecg.get_toy_ecg()  # 5 min of ECG data at 360 Hz
beats = sleepecg.detect_heartbeats(ecg, fs)

record = sleepecg.ECGRecord(
    ecg,
    fs,
    beats,
    id="scipy.misc.electrocardiogram()",
)

record.plot()
```

--------------------------------

### Plot Hypnogram with Sleep Stages and Heart Rate

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/plot.md

Generates a hypnogram visualizing sleep stages over time, optionally including heart rate information. The heart rate panel can help identify signal quality issues. Requires sleepecg and Matplotlib.

```python
import sleepecg

record = next(sleepecg.read_slpdb("*41*"))
sleepecg.plot_hypnogram(
    record,
    record.sleep_stages,
    "wake-rem-n1-n2-n3",
    show_bpm=True,
)
```

--------------------------------

### rri_similarity

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Calculates similarity measures between RR interval time series from detected and annotated heartbeats.

```APIDOC
## rri_similarity

### Description
Calculates similarity measures between RR interval time series from detected and annotated heartbeats. Returns Pearson correlation, Spearman correlation, and RMSE for evaluating detection accuracy in HRV analysis.

### Parameters
#### Arguments
- **detected** (array) - Required - Indices of detected heartbeats.
- **annotated** (array) - Required - Indices of ground truth heartbeats.
- **fs_resample** (int) - Optional - Sampling frequency for resampling the RRI time series.
```

--------------------------------

### read_slpdb

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Reads records from the MIT-BIH Polysomnographic Database (SLPDB) on PhysioNet, including automatic file downloading and heartbeat extraction.

```APIDOC
## read_slpdb

### Description
Reads records from the MIT-BIH Polysomnographic Database (SLPDB) on PhysioNet. Downloads required files automatically and extracts heartbeats from ECG signals.

### Parameters
#### Query Parameters
- **records_pattern** (str) - Optional - Pattern to match specific record IDs.
- **offline** (bool) - Optional - If True, disables automatic downloading of files.
```

--------------------------------

### Detect Heartbeats in ECG Signal

Source: https://github.com/cbrnr/sleepecg/blob/main/docs/heartbeat_detection.md

Finds heartbeats in an unfiltered ECG signal. Recommended sampling frequency is at least 100 Hz. The algorithm is robust to data scaling.

```python
from sleepecg import detect_heartbeats

beats = detect_heartbeats(ecg, fs)
```

--------------------------------

### Detect Heartbeats

Source: https://context7.com/cbrnr/sleepecg/llms.txt

Detects heartbeats in an ECG signal using the Pan & Tompkins algorithm. Supports C, Numba, and Python backends.

```python
import numpy as np
from sleepecg import detect_heartbeats, get_toy_ecg

# Load sample ECG data (5 minutes at 360 Hz)
ecg, fs = get_toy_ecg()

# Detect heartbeats
beats = detect_heartbeats(ecg, fs)
print(f"{len(beats)} heartbeats detected")
# Output: 478 heartbeats detected

# Calculate RR intervals in milliseconds
rri = 1000 * np.diff(beats) / fs
print(f"Mean RR interval: {np.mean(rri):.1f} ms")
print(f"Heart rate: {60000 / np.mean(rri):.1f} bpm")

# Use different backends
beats_numba = detect_heartbeats(ecg, fs, backend="numba")
beats_python = detect_heartbeats(ecg, fs, backend="python")
```