Skip to main content
`Ctrl`+`K`

# ada.data_containers.scored

## Classes

`PSGScore` | A class for storing and handling PSG staging.
`ScoredShort` | A class for storing and handling results of scoring by the short (nightly) algorithms.

## Module Contents

class PSGScore

  A class for storing and handling PSG staging.

  change_epoch(epoch_length, wake_percentage)

    Change epoch length from the original saved in tags to some other. Intended mainly to switch between 20, 30 and 60 second epochs and to downsample.

    Parameters:

      - epoch_length (int) – Output epoch length in seconds.

      - wake_percentage (float) – Parameter describing how many points inside a new epoch must be wake, so the new epoch will also be wake.

    Returns:

      New object with new epoch length.

    Return type:

      PSGScore

  export(path)

    Save psg scorings as a .ada file.

    Parameters:

      path (str) – Path to the output file.

  static load_file(path)

    Load data saved by the export method.

    Parameters:

      path (str) – Path to the file.

    Returns:

      Loaded data.

    Return type:

      PSGScore

  resample(new_fs)

    Resample scorings to new epoch length (primarly to synchronize them with fs of acigraphic data). Works when epoch length is longer than sample spacing in actigraphic data.

    Parameters:

      new_fs (float) – Sampling frequency to which sleep/wake scorings will be resampled.

    Returns:

      New object with resampled scorings.

    Return type:

      PSGScore

  property end_timestamp: float

    Unix timestamp of last epoch beginning.

    Return type:

      float

  property epoch_length: float

    Epoch length in seconds.

    Return type:

      float

  property psg_stages: numpy.ndarray | list

    Sleep/wake scorings.

    Return type:

      numpy.ndarray | list

  property start_timestamp: float

    Unix timestamp of first epoch beginning.

    Return type:

      float

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

  A class for storing and handling results of scoring by the short (nightly) algorithms.

  Parameters:

    - data (numpy.ndarray)

    - metadata (dict)

    - fs (float)

    - epoching_method_metadata (dict | None)

    - 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) – Sample after the last sample of output data.

    Returns:

      Object containing the cutted data.

    Return type:

      ScoredShort

  cut_by_timestamp(start_ts, end_ts)

    Create new object with the data cut by given timestamps.

    Parameters:

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

      - end_ts (float | None) – Unix 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:

      ScoredShort

  export(path)

    Exports object data to the generic format. All metadata are preserved in the file.

    Parameters:

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

  static load_file(path)

    Loading file saved in the generic format provided by this package.

    Parameters:

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

    Returns:

      Object containing data.

    Return type:

      ScoredShort

  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

    Unix timestamp of first sample.

    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