ada.io.mesa — ADA 1.0.3 documentation

Skip to main content
`Ctrl`+`K`

# ada.io.mesa

## Classes

`Mesa` | A class for storing data from the MESA dataset. Do not convert to generic!! These files are specific, are scored and epoched, but also do not contain absolute timestamp at all, and therefore are not compatible with Generic type.

## Module Contents

class Mesa(data, metadata, fs, epoching_method_metadata, scoring_method_metadata)

  A class for storing data from the MESA dataset. Do not convert to generic!! These files are specific, are scored and epoched, but also do not contain absolute timestamp at all, and therefore are not compatible with Generic type.

  Parameters:

    - data (numpy.ndarray)

    - metadata (dict)

    - fs (float)

    - epoching_method_metadata (dict)

    - scoring_method_metadata (dict)

  cut_by_dates(start_date, end_date)

    Create new object with the data cut by given dates.

    Parameters:

      - start_date (str) – ISO-formated date of outputa data beginning.

      - end_date (str | None) – ISO-formated date of output data end. If None, last sample of output data will be last sample of input data.

    Returns:

      Object containing the cutted data of the same type as input data.

    Return type:

      _ActiData

  cut_by_samples(start_sample, end_sample)

    Create new object with the data cut by given indexes.

    Parameters:

      - start_sample (int) – First sample of output data.

      - end_sample (int | None) – Sample after the last sample of output data. If None, last sample of output data will be last sample of input data.

    Returns:

      Object containing the cutted data.

    Return type:

      Mesa

  cut_by_timestamp(start_ts, end_ts)

    Create new object with the data cut by given timestamps.

    Parameters:

      - start_ts (float) – Relative timestamp of output data beginning.

      - end_ts (float | None) – Relative timestamp of output data end. If None, last sample of output data will be last sample of input data.

    Returns:

      Object containing the cutted data.

    Return type:

      Mesa

  export(path)

    Exports object data to the MESA-formatted csv.

    Parameters:

      path (str) – Path to the .csv file.

  static load_file(path)

    Loading file saved in the MESA format (csv).

    Parameters:

      path (str) – Path to the .csv file.

    Returns:

      Object containing data.

    Return type:

      Mesa

  long_sleep_episodes(length=5)

    Number of sleep episodes with length greater or equal to the one given in minutes.

    Parameters:

      length (int, optional) – Minutes of sleep required to sleep episode to be counted. Defaults to 5.

    Returns:

      Number of long sleep episodes.

    Return type:

      int

  mean_sleep_episode()

    Mean length of sleep episode in minutes.

    Returns:

      Mean length of sleep episode in minutes.

    Return type:

      float

  sleep_efficiency()

    Percentage of points classified as sleep in the recording.

    Returns:

      Sleep efficiency.

    Return type:

      float

  sleep_episodes()

    Number of episodes of continuous sleep, no matter their length

    Returns:

      Number of sleep episodes.

    Return type:

      int

  sleep_fragmentation_index()

    Defined as number of wake episodes during time in bed divided by total sleep time.

    Returns:

      Sleep fragmentaion index (1/min).

    Return type:

      float

  sleep_onset(minutes=20)

    Time (in minutes from beginning of the recording) after which first block of N minutes of sleep with at most 1 minute of wake begins.

    Parameters:

      minutes (int, optional) – Number of consecutive minutes of sleep required. Defaults to 20.

    Raises:

      RuntimeError – There is no consecutive N minutes of sleep in the data.

    Returns:

      Sleep onset.

    Return type:

      float

  sleep_report(minutes=20, length=5)

    Summary sleep report in stdout and in human-redable format.

    Parameters:

      - minutes (int, optional) – Number of consecutive minutes of sleep required when calculating sleep onset. Defaults to 20.

      - length (int, optional) – Minimal length of long sleep episode in minutes. Defaults to 5.

  total_sleep_time()

    Time classified as sleep during the recording.

    Returns:

      Total sleep time in minutes.

    Return type:

      float

  trim(time_from_start, time_from_end)

    Removes points from the recording beginning and end by given times.

    Parameters:

      - time_from_start (str | None) – Time in HH:MM:SS.sss from the recording beginning. Microseconds can be ommited. If None, data is returned from first sample.

      - time_from_end (str | None) – Time in HH:MM:SS.sss from the recording end. Microseconds can be ommited. If None, data is returned to the end sample.

    Returns:

      Trimmed data container of the same type as input one.

    Return type:

      _ActiData

  wake_after_sleep_onset(minutes=20)

    Time during which subject was awake between sleep onset and offset (here defined as last epoch scored as sleep).

    Parameters:

      minutes (int, optional) – Length of the time window, in minutes, used to calculate sleep onset (see sleep_onset for explanation). Defaults to 20.

    Returns:

      WASO (in minutes).

    Return type:

      float

  ActiData
  property channel_names: list[str]

    List of names for the channels stored in the data field.

    Return type:

      list[str]

  property data: numpy.ndarray

    Actigraphic data in format (n_channels, n_samples).

    Return type:

      numpy.ndarray

  property epoching_method_metadata: dict | None

    Metadata asssociated with the epoching method and its parameters. None if data was not epoched.

    Return type:

      dict | None

  property first_sample_timestamp: float

    Timestamp of first sample (relative)

    Return type:

      float

  property fs: float

    Sampling frequency of the data (not the same as recording frequency for epoched data).

    Return type:

      float

  property id: str

    ID of the recording set during device configuration.

    Return type:

      str

  property last_sample_timestamp: float

    Unix timestamp of last sample.

    Return type:

      float

  property metadata: dict

    Metadata associated with the raw recording and the device.

    Return type:

      dict

  property score: numpy.ndarray

    Vector containing sleep/wake scoring (1=wake).

    Return type:

      numpy.ndarray

  property scoring_method_metadata: dict

    Metadata asssociated with the scoring algorithm and its parameters.

    Return type:

      dict

  property timestamp: numpy.ndarray

    Unix timestamp of the data, relative to the recording beginning.

    Return type:

      numpy.ndarray

  property to_score: numpy.ndarray

    Data to be scored by scoring algorithms.

    Return type:

      numpy.ndarray