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[source]#

A class for storing and handling PSG staging.

change_epoch(epoch_length, wake_percentage)[source]#

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)[source]#

Save psg scorings as a .ada file.

Parameters:: path (str) – Path to the output file.

static load_file(path)[source]#

Load data saved by the export method.

Parameters:: path (str) – Path to the file.
Returns:: Loaded data.
Return type:: PSGScore

resample(new_fs)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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()[source]#

Mean length of sleep episode in minutes.

Returns:: Mean length of sleep episode in minutes.
Return type:: float

sleep_efficiency()[source]#

Percentage of points classified as sleep in the recording.

Returns:: Sleep efficiency.
Return type:: float

sleep_episodes()[source]#

Number of episodes of continuous sleep, no matter their length

Returns:: Number of sleep episodes.
Return type:: int

sleep_fragmentation_index()[source]#

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)[source]#

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)[source]#

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()[source]#

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)[source]#

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