Skip to main content

noctsleepy

A Python package for computing nocturnal sleep metrics from processed actigraphy data.

Build codecov Ruff stability-stable LGPL--2.1 License pages

Overview

noctsleepy is a Python-based toolbox for computing comprehensive sleep metrics from processed actigraphy data. Sleep metrics are computed from a user-defined nocturnal window, thus the impact of naps/secondary sleep can be removed if needed. The package handles timezone-aware processing, including proper daylight saving time (DST) transitions, and computes both individual night metrics and summary statistics across multiple nights.

Key Features

  • Comprehensive Sleep Metrics: Computes sleep duration, time in bed, sleep efficiency, wake after sleep onset (WASO), number of awakenings, sleep onset/wakeup times, and sleep midpoints.
  • DST-Aware Processing: Properly handles daylight saving time transitions using IANA timezone database, ensuring accurate sleep timing metrics during time changes.
  • Summary Statistics: Automatically computes mean and standard deviation for all requested metrics.
  • Flexible Nocturnal Windows: Users can define custom start and end times for the nocturnal interval.
  • Non-wear Filtering: Filters out nights with excessive non-wear time based on user-defined thresholds.

Installation

Install the noctsleepy package from PyPI via:

pip install noctsleepy

Quick Start

noctsleepy provides two flexible interfaces: a command-line tool for direct execution and an importable Python library.

Using noctsleepy through the command-line:

Basic usage:

noctsleepy /path/to/data.csv america/new_york

Custom parameters:

noctsleepy /path/to/data.csv europe/london \
  --night-start 22:00 \
  --night-end 07:00 \
  --nw-threshold 0.3 \
  --metrics sleep_duration \
  --metrics sleep_timing

For a full list of command line arguments:

noctsleepy --help

Using noctsleepy through a Python script or notebook:

import noctsleepy
import pathlib
import datetime

# Define input file path
input_path = pathlib.Path("/path/to/your/data.csv")

# Compute all sleep metrics
sleep_metrics = noctsleepy.compute_sleep_metrics(
    input_data=input_path, timezone="America/New_York"
)

# Compute custom pipeline
custom_metrics = noctsleepy.compute_sleep_metrics(
    input_data=input_path,
    timezone="America/Toronto",
    night_start=datetime.time(22, 0),
    night_end=datetime.time(6, 0),
    nw_threshold=0.15,
    selected_metrics=["sleep_continuity", "sleep_timing"],
)

# Access computed metrics
sleep_duration = sleep_metrics.sleep_duration
sleep_onset = sleep_metrics.sleep_onset
sleep_efficiency = sleep_metrics.sleep_efficiency

Input Data Requirements

noctsleepy requires processed actigraphy data with the following columns:

  • time: Timestamps for each data point, it should be a singular sampling rate.
  • sib_periods: Boolean indicating sustained inactivity bouts (sleep detection).
  • spt_periods: Boolean indicating sleep period time windows.
  • nonwear_status: Boolean indicating non-wear periods.

The input data should ideally be processed with wristpy or have a compatible output format. Supported input formats include CSV and Parquet files.

Computed Sleep Metrics

All metrics are computed only during the defined nocturnal window, any sleep that occurs outside of this window is ignored.

Sleep Duration Metrics

  • sleep_duration: Total sleep time in minutes (sum of sustained inactivity bouts within sleep period time).
  • time_in_bed: Total time in bed in minutes (duration of sleep period time windows).

Sleep Continuity Metrics

  • sleep_efficiency: Ratio of total sleep time to time in bed, as a percentage.
  • waso: Wake After Sleep Onset, in minutes.
  • num_awakenings: Number of awakening episodes during the sleep period.
  • waso_30: Number of nights with WASO exceeding 30 minutes (normalized to 30-day protocol).

Sleep Timing Metrics

  • sleep_onset: Time when the first sleep period starts (HH:MM format).
  • sleep_wakeup: Time when the last sleep period ends (HH:MM format).
  • sleep_midpoint: Midpoint of the sleep period (HH:MM format).
  • weekday_midpoint: Average sleep midpoint on weekdays (Monday-Friday).
  • weekend_midpoint: Average sleep midpoint on weekends (Saturday-Sunday).
  • social_jetlag: Absolute difference between weekend and weekday midpoints, in hours.

Summary Statistics

For each metric, noctsleepy automatically computes:

  • Mean: Average value across all valid nights
  • Standard Deviation: Measure of variability across nights
    • Duration metrics use standard statistics
    • Time-based metrics use circular statistics to properly handle times crossing midnight

Handling Timezones and Daylight Saving Time

noctsleepy requires users to specify a timezone-aware location using IANA timezone database names (e.g., America/New_York, Europe/London). The package properly handles DST transitions:

Wall-Clock vs. Anatomical Clock

  • Wall-clock metrics (sleep onset, wakeup, midpoint): Reported based on the local time displayed on a clock
  • Anatomical clock metrics (sleep duration, time in bed, WASO, sleep efficiency): Account for actual elapsed time, including DST changes.

Example: During a "fall back" DST transition, if someone sleeps from 10:00 PM to 6:00 AM (wall-clock time), their sleep duration will reflect the additional hour gained during the transition (9 hours of actual sleep), while the onset/wakeup times show the wall-clock times (10:00 PM and 6:00 AM).

Supported Timezones

noctsleepy supports timezones across many regions, including:

  • North America: us_eastern, us_central, us_mountain, us_pacific, us_alaska, us_hawaii, canada_eastern, mexico_central, etc.
  • Europe: europe_london, europe_paris, europe_berlin, europe_rome, europe_moscow, etc.
  • Asia: asia_tokyo, asia_shanghai, asia_kolkata, asia_singapore, asia_dubai, etc.
  • South America: brazil_eastern, argentina, chile, colombia, etc.
  • Africa: africa_cairo, africa_johannesburg, africa_nairobi, africa_lagos, etc.
  • Oceania: australia_sydney, australia_melbourne, new_zealand, pacific_fiji, etc.

For a complete list of supported timezones, run:

noctsleepy compute-metrics --help

Output Format

Results are automatically saved as a JSON file in the same directory as the input file, containing both per night statistics and summary statistics.

Support

For questions, bug reports, or feature requests, please open an issue on GitHub.

Metadata

Release files for noctsleepy 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for noctsleepy 0.1.5
File Size Uploaded Provenance Actions
noctsleepy-0.1.5.tar.gz 332.8 kB Without provenance Details for noctsleepy-0.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for noctsleepy 0.1.5
File Interpreter ABI Platform Actions
noctsleepy-0.1.5-py3-none-any.whl Python 3 none any Details for noctsleepy-0.1.5-py3-none-any.whl

Total release size: 361.4 kB

Release files / noctsleepy-0.1.5.tar.gz

Download URL noctsleepy-0.1.5.tar.gz
Size 332.8 kB
Tags Source
SHA-256 checksum
How to use checksums
aaed47627689192c386e277f5b74b467729940ec16083b0a5d82e6e3a8e760be
BLAKE2b-256 checksum
How to use checksums
5e53f68ef35602e69e57cad4da5e9790bed73b68f9f7823c8af62379da1f90a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / noctsleepy-0.1.5-py3-none-any.whl

Download URL noctsleepy-0.1.5-py3-none-any.whl
Size 28.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e6134ee7dc5033eadfec923b3b301ad92780db22e5963f856cea7486615a3d2
BLAKE2b-256 checksum
How to use checksums
95d33b9667a77593f9299c9b91ec80ef5c4c2527beeff71ceb8d2684f1303ab1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for noctsleepy 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page