Skip to content

Download from NSRR

Download files from a dataset on the National Sleep Research Resource (NSRR).

Synopsis

somnio download-nsrr SLUG OUTPUT_DIR [OPTIONS]

See CLI for the full reference.

Before you start

Install extras

download-nsrr is a CLI command and requires both the cli and nsrr extras (see Installation).

Get an NSRR token

  • Create an account at sleepdata.org.
  • Request access to the dataset (e.g. SOF, SHHS, MESA).
  • After approval, copy your auth token from the dataset page or account profile.
  • Pass it with --token or set the NSRR_TOKEN environment variable (e.g. in .env).

Output layout

Files are placed under OUTPUT_DIR/SLUG/. If you use --path, only that subpath is created. For example:

  • somnio download-nsrr sof ./data ... → ./data/sof/...
  • somnio download-nsrr shhs ./data --path polysomnography ... → ./data/shhs/polysomnography/...

Examples

Full dataset

Download the full SOF dataset into ./data:

somnio download-nsrr sof ./data --token YOUR_NSRR_TOKEN

Single subpath

Download only the polysomnography folder from SHHS:

somnio download-nsrr shhs ./data --path polysomnography --token YOUR_NSRR_TOKEN

Using the environment for the token

Avoid putting the token on the command line by setting NSRR_TOKEN (e.g. in .env or your shell):

export NSRR_TOKEN=your_token_here
somnio download-nsrr sof ./data

Longer timeout and file logging

Use a 10-minute timeout and write logs to the default logs/ file:

somnio -l download-nsrr mesa ./datasets --token YOUR_NSRR_TOKEN --timeout-seconds 600

Custom log file

Send debug logs to a specific file for later inspection:

somnio --log-file ./nsrr-debug.log download-nsrr shhs ./data --token YOUR_NSRR_TOKEN

Retries and timeouts

For flaky connections or slow networks, use --timeout-seconds to increase the per-request timeout. You can also tune --download-retries (retries per file on connection/read timeout) and --http-retries (retries for API requests). See the CLI reference for defaults and details.

TLS verification

sleepdata.org currently sends an incomplete TLS certificate chain, which can cause download failures with the default verify settings. Use either:

  • --no-verify to skip certificate verification (convenient for local downloads; less secure)
  • --ca-bundle /path/to/bundle.pem to supply a CA bundle that includes the missing intermediates (overrides --verify / --no-verify)
somnio download-nsrr sof ./data --token YOUR_NSRR_TOKEN --no-verify

somnio download-nsrr sof ./data --token YOUR_NSRR_TOKEN --ca-bundle ./sleepdata-ca-bundle.pem