lunapi.moonbeam

Moonbeam client API.

This module exports moonbeam, a helper for querying NSRR Moonbeam catalog metadata and downloading EDF/annotation assets into a local cache.

Classes

moonbeam

Client for the NSRR Moonbeam data catalog.

Module Contents

class lunapi.moonbeam.moonbeam(nsrr_tok, cdir=None)

Client for the NSRR Moonbeam data catalog.

Moonbeam provides programmatic access to sleep study cohorts hosted by the National Sleep Research Resource (NSRR). This class handles authentication, catalog queries, file downloads with progress bars, and automatic Luna instance creation from cached data.

Parameters:

• nsrr_tok (str) – Your personal NSRR API token.

• cdir (str, optional) – Local directory used as the download cache. Defaults to a luna-moonbeam sub-folder inside the system temporary directory.

Examples

>>> mb = moonbeam('my-nsrr-token')
>>> mb.cohorts()
>>> mb.cohort('shhs1')
>>> p = mb.inst('shhs1-200001')

df1 = None

df2 = None

curr_cohort = None

nsrr_tok

set_cache(cdir)

Set the local folder used to cache downloaded files.

Parameters:

cdir (str) – Path to the desired cache directory. The directory (and any missing parent directories) will be created automatically.

Return type:

None

cached(file)

Return whether file already exists in the local cache.

Parameters:

file (str) – File path relative to the cache root (typically <cohort>/<filename>).

Returns:

True if the file is present in the cache; False otherwise.

Return type:

bool

cohorts()

Fetch the list of NSRR cohorts accessible with the current token.

Returns:

DataFrame with columns ['Cohort', 'Description'].

Return type:

pandas.DataFrame

cohort(cohort1)

Fetch the file manifest for a given cohort and set it as current.

Parameters:

cohort1 (str or int) – Cohort identifier string (e.g. 'shhs1') or integer row index into the DataFrame returned by cohorts().

Returns:

DataFrame with columns ['ID', 'EDF', 'Annot'], one row per individual in the cohort.

Return type:

pandas.DataFrame

inst(iid)

Return a Luna instance for one individual, downloading files if needed.

Calls pull() to ensure the EDF (and annotation file, if present) are available in the local cache, then creates and returns a fully attached inst object.

A call to cohort() must have been made first to set the current cohort and populate the file manifest.

Parameters:

iid (str or int) – Individual ID string, or integer row index into the DataFrame returned by cohort().

Returns:

Attached instance, or None if no cohort has been set.

Return type:

lunapi.instance.inst or None

pull(iid, cohort)

Download an individual’s EDF and annotation files (if not cached).

Downloads the EDF (and its .idx companion for compressed files) as well as the annotation file (if one is listed in the manifest). Files that are already present in the cache are skipped.

Parameters:

• iid (str or int) – Individual ID string, or integer row index into the cohort manifest DataFrame.

• cohort (str) – Cohort identifier (must match the current cohort set by cohort()).

Return type:

None

pull_file(file)

Download a single file from Moonbeam into the local cache.

If file is already present in the cache the download is skipped. Progress is displayed via a tqdm progress bar.

Parameters:

file (str) – Remote file path as returned by the Moonbeam catalog (e.g. 'shhs1/shhs1-200001.edf.gz').

Return type:

None

Raises:

RuntimeError – If the HTTP response status code indicates an error.

pheno(cohort=None, iid=None)

Fetch phenotype data for an individual from Moonbeam.

If cohort and iid are omitted, the method uses the cohort and individual set by the most recent pull() or inst() call.

Parameters:

• cohort (str, optional) – Cohort identifier. Defaults to the current cohort.

• iid (str, optional) – Individual ID. Defaults to the most recently accessed individual.

Returns:

DataFrame with columns ['Variable', 'Value', 'Units', 'Description']. Key NSRR harmonised variables (age, sex, BMI, AHI, etc.) are listed first.

Return type:

pandas.DataFrame

Raises:

RuntimeError – If the Moonbeam server returns a non-200 status code.