Data types

Data types#

Actigraphic data#

All data containers implement following basic getters:

  • data is a numpy matrix storing all the recorded data, in the shape (n_channels, n_samples)

  • metadata is a dictionary with fields dependent on a device used to record the data

  • fs which stores sampling frequency

  • channel_names are in the same order as channels in data

  • timestamp stored in Unix format and relative to the recording beginning

  • first_sample_timestamp in Unix format

  • last_sample_timestamp in Unix format

  • id is a string with the subjects ID (set during device setup)

There is also generic format available. It is advised to convert raw data into the generic format prior to exporting (or to export as generic using FileManager), as the generic files are much faster to read than the ones provided by manufacturers.

Raw data#

Containers designed for storing non-epoched, tri-axial data from MEMS based devices. They all give access to:

  • x, y and z: acceleration along given axis stored in g

  • to_score: equivalent to \(|\sqrt{x^2 + y ^2 + z^2} - 1|\)

  • stationary_variance: variance of actigraph lying down without movement

  • dynamic_range: absolute value of maximal/minimal acceleration possible to record

Some of them give access to more fields, e.g. light or temperature sensors. Please consult the API Reference

Epoched data#

Containers designed for storing epoched (including standard downsampling) data. They give access to:

  • to_score which is the result of epoching algorithm

  • epoching_method_metadata is a dictionary storing metadata regarding used epoching method and its settings

Scored data#

Results of scoring using short methods (e.g. unified filter or Cole-Kripke). They give access to:

  • score: a binary sleep/wake classification with 0 meaning sleep

  • scoring_method_metadata is a dictionary storing metadata regarding used scoring smethod and its settings

These objects also implement methods computing various sleep metrics. Please consult the API Reference

Actigraphy with PSG#

ActiPSG#

Container for synchronized actigraphic data (any of the described above) and polysomnographic staging. The data are synchronized, and the sampling frequency of PSG scoring is changed to match the actigraphic data.

Following getters are implemented:

  • acti_data

  • eeg_data

  • timestamp

  • first_sample_timestamp

  • last_sample_timestamp

PSG scorings#

Container for PSG scorings is implemented as PSGScore. Following getters are implemented:

  • psg_stages: a list with either strings (when containing full staging) or booleans (when containing sleep/wake classification). Only staging in epochs of equal length is supported.

  • start_timestamp: beginning of the first epoch in Unix timestamp

  • end_timestamp: beginning of the last epoch in Unix timestamp

  • epoch_length in seconds

Long Results#

Each algorithm for circadian rhythms estimation returns its own container with the results of fit. They all implement the following:

  • fit_params: a dictionary with complete set of parameters used and derived during fitting

  • id is a string with the subjects ID (set during device setup) and depends on the data to which model was fit

  • plot() allows plotting of the results (which differ greatly between algorithms)

Specific containers give access to various different fields. Please consult the API Reference.

MESA dataset#

ADA has a separate container for storing data from MESA dataset. These are quite unusual, as .csv from MESA contain both epoched activity counts and sleep/wake scoring derived from them. Mesa inherits properties of both Epoched and Scored types, giving access to both to_score and score vectors.

However, MESA is stripped of start dates due to anonimization process, therefore first_sample_timestamp is equivalent to timestamp[0].

Do not convert MESA to Generic format, due to the lack of absolute start date.

ADA formats specification#

.ada format is a ZIP file containing at least the following .npy files:

  • arr_0, which contains all data (actigraphic data, timestamp vector, any additional data e.g. from light sensors).

  • arr_1, which contains metadata of the raw recording (the contents will vary based on manufacturer).

  • arr_2, which contains the meta-metadata, namely: list of channel names, sampling frequency of data and descriptors of each file in the ZIP (which file contains which type of data).

Additionally, more files might be present, containing epohcing method metadata and sleep/wake scoring method metadata. Their content will always be described in the meta-metadata.

Sampling frequency from the meta-metadata is the sampling of time-series present in the data, therefore it will not be equal to the sampling frequency stored in metadata in case of epoched data.

.ada.long file is a ZIP file containing 2 .npy files:

  • arr_0, which contains the data corresponding to the model (e.g. frequency axis and power density in case of AR spectrum). It might also be empty (e.g. in case of cosinor).

  • arr_1, which contains the parameters of the model fitted to the data and stored in respective Long container prior to exporting.

Generic CSV, used to store actigraphic time-series in a way easy to read in different programming languages (but inefective in terms of space and reading speed) is organized using a series of headers:

  • First line is always: ‘—GENERIC CSV GENERATED BY ADA—’ followed by line with sampling frequency of the time-series and a blank line.

  • Next, the headers ‘—METADATA—’, ‘—EPOCHING METADATA—’ and ‘—SCORING METADATA—’ separate blocks of rows contating respective content (which might be empty).

  • Lastly, the header ‘—DATA—’ marks the beginning of time-series. It is followed by a row containing channels names, after which the data stream begins.

Contents