Data types — ADA 1.0.3 documentation

Skip to main content
`Ctrl`+`K`

# 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.