lunapi.moonbeam
===============

.. py:module:: lunapi.moonbeam

.. autoapi-nested-parse::

   Moonbeam client API.

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



Classes
-------

.. autoapisummary::

   lunapi.moonbeam.moonbeam


Module Contents
---------------

.. py:class:: 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.

   :param nsrr_tok: Your personal NSRR API token.
   :type nsrr_tok: str
   :param cdir: Local directory used as the download cache.  Defaults to a
                ``luna-moonbeam`` sub-folder inside the system temporary directory.
   :type cdir: str, optional

   .. rubric:: Examples

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


   .. py:attribute:: df1
      :value: None



   .. py:attribute:: df2
      :value: None



   .. py:attribute:: curr_cohort
      :value: None



   .. py:attribute:: nsrr_tok


   .. py:method:: set_cache(cdir)

      Set the local folder used to cache downloaded files.

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

      :rtype: None



   .. py:method:: cached(file)

      Return whether *file* already exists in the local cache.

      :param file: File path relative to the cache root (typically
                   ``<cohort>/<filename>``).
      :type file: str

      :returns: ``True`` if the file is present in the cache; ``False`` otherwise.
      :rtype: bool



   .. py:method:: cohorts()

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

      :returns: DataFrame with columns ``['Cohort', 'Description']``.
      :rtype: pandas.DataFrame



   .. py:method:: cohort(cohort1)

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

      :param cohort1: Cohort identifier string (e.g. ``'shhs1'``) or integer row index
                      into the DataFrame returned by :meth:`cohorts`.
      :type cohort1: str or int

      :returns: DataFrame with columns ``['ID', 'EDF', 'Annot']``, one row per
                individual in the cohort.
      :rtype: pandas.DataFrame



   .. py:method:: inst(iid)

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

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

      A call to :meth:`cohort` must have been made first to set the current
      cohort and populate the file manifest.

      :param iid: Individual ID string, or integer row index into the DataFrame
                  returned by :meth:`cohort`.
      :type iid: str or int

      :returns: Attached instance, or ``None`` if no cohort has been set.
      :rtype: lunapi.instance.inst or None



   .. py:method:: 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.

      :param iid: Individual ID string, or integer row index into the cohort
                  manifest DataFrame.
      :type iid: str or int
      :param cohort: Cohort identifier (must match the current cohort set by
                     :meth:`cohort`).
      :type cohort: str

      :rtype: None



   .. py:method:: 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.

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

      :rtype: None

      :raises RuntimeError: If the HTTP response status code indicates an error.



   .. py:method:: 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 :meth:`pull` or :meth:`inst` call.

      :param cohort: Cohort identifier.  Defaults to the current cohort.
      :type cohort: str, optional
      :param iid: Individual ID.  Defaults to the most recently accessed individual.
      :type iid: str, optional

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

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