somnio 0.1.0__tar.gz

somnio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Saberi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

somnio-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.3
+Name: somnio
+Version: 0.1.0
+Summary: Python library and CLI for sleep and physiological data workflows.
+Keywords: sleep,physiology,polysomnography,hdf5,eeg,biosignals,neuroscience,zmax
+Author: Ali Saberi
+Author-email: Ali Saberi <ali.saberi96@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 Ali Saberi
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: numpy>=1.24
+Requires-Dist: loguru>=0.7.3 ; extra == 'cli'
+Requires-Dist: python-dotenv>=1.0.0 ; extra == 'cli'
+Requires-Dist: requests>=2.31.0 ; extra == 'cli'
+Requires-Dist: tqdm>=4.67.3 ; extra == 'cli'
+Requires-Dist: typer>=0.21.1 ; extra == 'cli'
+Requires-Dist: edfio>=0.4 ; extra == 'edf'
+Requires-Dist: mne>=1.5 ; extra == 'edf'
+Requires-Dist: h5py>=3.8 ; extra == 'hdf5'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/alitsaberi/somnio
+Project-URL: Repository, https://github.com/alitsaberi/somnio
+Project-URL: Documentation, https://alitsaberi.github.io/somnio/
+Project-URL: Issues, https://github.com/alitsaberi/somnio/issues
+Provides-Extra: cli
+Provides-Extra: edf
+Provides-Extra: hdf5
+Description-Content-Type: text/markdown
+
+# Somnio
+
+Python library and CLI for sleep and physiological data workflows.
+
+## Install
+
+```bash
+pip install somnio
+```
+
+Optional extras:
+
+- `somnio[cli]` — command-line tools
+- `somnio[hdf5]` — `somnio.io.hdf5` layouts (requires [h5py](https://www.h5py.org/))
+
+With **uv**: `uv add somnio`, `uv add somnio[cli]`, or `uv add somnio[hdf5]`.
+
+## Documentation
+
+Site source lives under [`docs/`](docs/). Build or serve locally (with the `docs` dependency group installed):
+
+```bash
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Reference material includes [data types](docs/reference/data.md) and [I/O / HDF5](docs/reference/io.md).

somnio-0.1.0/README.md

@@ -0,0 +1,27 @@
+# Somnio
+
+Python library and CLI for sleep and physiological data workflows.
+
+## Install
+
+```bash
+pip install somnio
+```
+
+Optional extras:
+
+- `somnio[cli]` — command-line tools
+- `somnio[hdf5]` — `somnio.io.hdf5` layouts (requires [h5py](https://www.h5py.org/))
+
+With **uv**: `uv add somnio`, `uv add somnio[cli]`, or `uv add somnio[hdf5]`.
+
+## Documentation
+
+Site source lives under [`docs/`](docs/). Build or serve locally (with the `docs` dependency group installed):
+
+```bash
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Reference material includes [data types](docs/reference/data.md) and [I/O / HDF5](docs/reference/io.md).

somnio-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "somnio"
+version = "0.1.0"
+description = "Python library and CLI for sleep and physiological data workflows."
+readme = "README.md"
+authors = [
+    { name = "Ali Saberi", email = "ali.saberi96@gmail.com" }
+]
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+keywords = [
+    "sleep",
+    "physiology",
+    "polysomnography",
+    "hdf5",
+    "eeg",
+    "biosignals",
+    "neuroscience",
+    "zmax"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.urls]
+Homepage = "https://github.com/alitsaberi/somnio"
+Repository = "https://github.com/alitsaberi/somnio"
+Documentation = "https://alitsaberi.github.io/somnio/"
+Issues = "https://github.com/alitsaberi/somnio/issues"
+
+[project.scripts]
+somnio = "somnio.cli.main:app"
+
+[project.optional-dependencies]
+hdf5 = ["h5py>=3.8"]
+cli = [
+    "loguru>=0.7.3",
+    "python-dotenv>=1.0.0",
+    "requests>=2.31.0",
+    "tqdm>=4.67.3",
+    "typer>=0.21.1",
+]
+edf = [
+    "edfio>=0.4",
+    "mne>=1.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    {include-group = "lint"},
+    {include-group = "docs"},
+    {include-group = "test"},
+    "pre-commit>=4.5.1",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.0",
+    "mkdocs-typer2>=0.2.0",
+    "pymdown-extensions>=10.14.0",
+]
+lint = [
+    "ruff>=0.14.14",
+]
+test = [
+    "pytest>=9.0.2",
+    "h5py>=3.8",
+    "mne>=1.5",
+    "edfio>=0.4",
+]
+
+[tool.uv.dependency-groups]
+dev = {requires-python = ">=3.12"}
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint]
+# Enforce a consistent TODO convention:
+# - Use TODO (not FIXME/XXX)
+# - Keep formatting consistent after `TODO:` / `TODO(name):`
+# Note: We intentionally do NOT require authors (TD002) or issue links (TD003).
+extend-select = ["TD001", "TD007"]
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = "dynamic"

somnio-0.1.0/src/somnio/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())

somnio-0.1.0/src/somnio/cli/__init__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+__all__ = ["app"]

somnio-0.1.0/src/somnio/cli/commands/nsrr.py

@@ -0,0 +1,202 @@
+"""NSRR (National Sleep Research Resource) dataset download commands."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import typer
+from loguru import logger
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+import requests
+from tqdm import tqdm
+
+
+DEFAULT_HTTP_RETRIES = 6
+RETRY_STATUS_FORCELIST = (429, 500, 502, 503, 504)
+
+DEFAULT_TIMEOUT_SECONDS = 300.0
+DEFAULT_DOWNLOAD_RETRIES = 3
+DOWNLOAD_RETRY_DELAY_SECONDS = 10
+DOWNLOAD_RETRY_EXCEPTIONS = (
+    requests.exceptions.ConnectionError,
+    requests.exceptions.ReadTimeout,
+)
+
+
+def _build_session(http_retries: int = DEFAULT_HTTP_RETRIES) -> requests.Session:
+    """Create a requests Session with retries for transient NSRR issues.
+
+    NSRR occasionally returns 502/503/504; we retry those with exponential backoff.
+    """
+    retry = Retry(
+        total=http_retries,
+        connect=http_retries,
+        read=http_retries,
+        status=http_retries,
+        backoff_factor=1.0,
+        status_forcelist=RETRY_STATUS_FORCELIST,
+        allowed_methods=frozenset(["GET"]),
+        raise_on_status=False,
+        respect_retry_after_header=True,
+    )
+    adapter = HTTPAdapter(max_retries=retry)
+    session = requests.Session()
+    session.mount("https://", adapter)
+    session.mount("http://", adapter)
+    return session
+
+
+def _fetch_directory_listing(
+    session: requests.Session,
+    slug: str,
+    token: str,
+    path: str | None = None,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+) -> list:
+    """Fetch one level of the dataset file listing from the NSRR API."""
+    base_url = f"https://sleepdata.org/api/v1/datasets/{slug}/files.json"
+    params: dict[str, str] = {"auth_token": token}
+    if path:
+        params["path"] = path
+    response = session.get(base_url, params=params, timeout=timeout_seconds)
+    try:
+        response.raise_for_status()
+    except requests.HTTPError as e:
+        snippet = (response.text or "")[:500].replace("\n", " ").strip()
+        raise requests.HTTPError(
+            f"{e} (status={response.status_code}) url={response.url} body_snippet={snippet!r}"
+        ) from e
+    return response.json()
+
+
+def _collect_all_files(
+    session: requests.Session,
+    slug: str,
+    token: str,
+    path: str | None = None,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+) -> list:
+    """Recursively collect all file entries under the given path."""
+    files: list[dict] = []
+    items = _fetch_directory_listing(
+        session, slug, token, path, timeout_seconds=timeout_seconds
+    )
+    for item in items:
+        if item["is_file"]:
+            files.append(item)
+        else:
+            files += _collect_all_files(
+                session, slug, token, item["full_path"], timeout_seconds=timeout_seconds
+            )
+    return files
+
+
+def _download_file(
+    session: requests.Session,
+    slug: str,
+    token: str,
+    file_obj: dict,
+    base_dir: Path,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+) -> None:
+    """Download a single file from NSRR, creating parent dirs and skipping if complete."""
+    download_url = (
+        f"https://sleepdata.org/datasets/{slug}/files/{file_obj['full_path']}"
+        f"?auth_token={token}"
+    )
+    local_path = base_dir / file_obj["full_path"]
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if local_path.exists():
+        expected_size = file_obj.get("size")
+        if expected_size is not None:
+            if local_path.stat().st_size == expected_size:
+                logger.debug("Skipping (exists, size match): {}", file_obj["full_path"])
+                return
+        else:
+            logger.debug("Skipping (exists): {}", file_obj["full_path"])
+            return
+
+    logger.debug("Downloading {}...", file_obj["full_path"])
+    with session.get(download_url, stream=True, timeout=timeout_seconds) as r:
+        r.raise_for_status()
+        with local_path.open("wb") as f:
+            for chunk in r.iter_content(chunk_size=8192):
+                f.write(chunk)
+    logger.debug("Saved to {}", local_path)
+
+
+def download(
+    slug: str = typer.Argument(..., help="Dataset slug (e.g., sof, shhs, mesa)."),
+    output_dir: Path = typer.Argument(
+        ...,
+        path_type=Path,
+        help="Output directory; files are written to OUTPUT_DIR/SLUG/.",
+    ),
+    token: str | None = typer.Option(
+        ...,
+        "--token",
+        "-t",
+        envvar="NSRR_TOKEN",
+        help="NSRR auth token.",
+    ),
+    path: str = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Subpath to download (e.g., polysomnography). Default: entire dataset.",
+    ),
+    timeout_seconds: float = typer.Option(
+        DEFAULT_TIMEOUT_SECONDS,
+        "--timeout-seconds",
+        help="Per-request timeout in seconds.",
+    ),
+    download_retries: int = typer.Option(
+        DEFAULT_DOWNLOAD_RETRIES,
+        "--download-retries",
+        help="Retries per file on connection/read timeout.",
+    ),
+    http_retries: int = typer.Option(
+        DEFAULT_HTTP_RETRIES,
+        "--http-retries",
+        help="Retries for HTTP requests.",
+    ),
+) -> None:
+    """Download files from an NSRR dataset."""
+
+    if not token:
+        logger.error("Missing NSRR token. Set NSRR_TOKEN in .env or pass --token.")
+        raise SystemExit(1)
+
+    session = _build_session(http_retries=http_retries)
+    target_path = path.strip() if path else None
+    all_files = _collect_all_files(
+        session, slug, token, target_path, timeout_seconds=timeout_seconds
+    )
+    logger.info("Found {} files under {!r}.", len(all_files), target_path or "(root)")
+
+    out = output_dir / slug
+    for file_obj in tqdm(all_files, desc="Downloading", unit="file"):
+        for attempt in range(1, download_retries + 1):
+            try:
+                _download_file(
+                    session,
+                    slug,
+                    token,
+                    file_obj,
+                    out,
+                    timeout_seconds=timeout_seconds,
+                )
+                break
+            except DOWNLOAD_RETRY_EXCEPTIONS as e:
+                if attempt == download_retries:
+                    raise
+
+                delay = attempt * DOWNLOAD_RETRY_DELAY_SECONDS
+                tqdm.write(
+                    f"Timeout/connection error, retrying in {delay}s... "
+                    f"(attempt {attempt}/{download_retries}, {e!r})"
+                )
+                time.sleep(delay)

somnio-0.1.0/src/somnio/cli/main.py

@@ -0,0 +1,69 @@
+"""Somnio CLI app.
+
+This module is the console entry point target.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+from loguru import logger
+import typer
+
+from .commands.nsrr import download as download_nsrr
+from .utils.logging import (
+    DEFAULT_LOG_DIRECTORY,
+    DEFAULT_LOG_FILE_NAME,
+    create_log_file_path,
+    setup_logging,
+)
+
+
+def create_app() -> "typer.Typer":
+    """Create a new CLI app instance.
+
+    Tests should prefer this factory to avoid mutating global app state.
+    """
+
+    app = typer.Typer()
+    app.command("download-nsrr")(download_nsrr)
+
+    @app.callback()
+    def _main_callback(
+        ctx: typer.Context,
+        file_logging: bool = typer.Option(
+            False,
+            "-l",
+            "--file-logging",
+            help=f"Enable file logging. By default, logs are written to {DEFAULT_LOG_DIRECTORY}/{DEFAULT_LOG_FILE_NAME}. Use before the subcommand.",
+        ),
+        log_file: Path | None = typer.Option(
+            None,
+            "-f",
+            "--log-file",
+            path_type=Path,
+            help="Log to this file instead of the default. Implies file logging. Must appear before the subcommand.",
+        ),
+    ) -> None:
+        if file_logging and log_file is None:
+            command_name = ctx.invoked_subcommand or app.info.name
+            log_file = create_log_file_path(command_name)
+
+        setup_logging(log_file=log_file)
+        logger.debug(
+            "CLI: command={} subcommand={} params={} args={}",
+            ctx.info_name,
+            ctx.invoked_subcommand,
+            ctx.params,
+            ctx.args,
+        )
+
+    return app
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    app()

somnio-0.1.0/src/somnio/cli/utils/logging.py

@@ -0,0 +1,84 @@
+"""Logging utilities for the somnio CLI.
+
+This module configures Loguru as the primary logger and bridges standard-library
+``logging`` records into Loguru.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+import logging
+import sys
+from pathlib import Path
+from types import FrameType
+
+from loguru import logger
+
+
+DEFAULT_STDERR_LOG_LEVEL = "INFO"
+DEFAULT_FILE_LOG_LEVEL = "DEBUG"
+DEFAULT_LOG_DIRECTORY = Path("logs")
+DEFAULT_LOG_FILE_NAME = "{command}_{timestamp}.log"
+
+# Redact auth_token (and similar) from log messages so tokens never appear in logs.
+_REDACT_PATTERN = re.compile(
+    r"(auth_token|token)=[^&\s\"']+",
+    re.IGNORECASE,
+)
+_TIMESTAMP_FORMAT = "%Y%m%d_%H%M%S"
+
+
+class _InterceptHandler(logging.Handler):
+    """Forward stdlib logging records to Loguru."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level: str | int = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame: FrameType | None = logging.currentframe()
+        depth = 2
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(
+            level, record.getMessage()
+        )
+
+
+def _redact_sensitive(record: dict) -> bool:
+    """Filter that redacts token values in log messages. Mutates record and returns True."""
+    record["message"] = _REDACT_PATTERN.sub(r"\1=***", record["message"])
+    return True
+
+
+def setup_logging(
+    *,
+    stderr_level: str = DEFAULT_STDERR_LOG_LEVEL,
+    file_level: str = DEFAULT_FILE_LOG_LEVEL,
+    log_file: Path | None = None,
+) -> None:
+    """Configure Loguru and bridge stdlib logging to it."""
+
+    logger.remove()
+    logger.add(sys.stderr, level=stderr_level, filter=_redact_sensitive)
+
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        logger.add(log_file, level=file_level, filter=_redact_sensitive)
+        logger.info("Logging to {}", log_file)
+
+    # Bridge stdlib logging -> Loguru (for library modules using `logging`)
+    logging.root.handlers = [_InterceptHandler()]
+    logging.root.setLevel(logging.NOTSET)
+
+
+def create_log_file_path(command: str) -> Path:
+    """Create a log file path for a given script name."""
+    timestamp = datetime.now().strftime(_TIMESTAMP_FORMAT)
+    return DEFAULT_LOG_DIRECTORY / DEFAULT_LOG_FILE_NAME.format(
+        command=command, timestamp=timestamp
+    )

somnio-0.1.0/src/somnio/data/__init__.py

@@ -0,0 +1,20 @@
+"""somnio.data — in-memory data types for sleep signal data."""
+
+from somnio.data.annotations import (
+    Event,
+    Epochs,
+    epochs_to_events,
+    events_to_epochs,
+)
+from somnio.data.timeseries import Sample, TimeSeries, collect_samples, concat
+
+__all__ = [
+    "Sample",
+    "TimeSeries",
+    "collect_samples",
+    "concat",
+    "Event",
+    "Epochs",
+    "epochs_to_events",
+    "events_to_epochs",
+]

somnio-0.1.0/src/somnio/data/adapters/__init__.py

@@ -0,0 +1 @@
+"""Optional bridges from somnio types to third-party in-memory APIs."""