Quickstart

The following exapmles provide a general introduction into the main stages of processing data using ADA:

1. Reading and writing data

2. Collapsing into epochs

3. Sleep/wake scoring

4. Estimating circadian rhythms

Aside from minor syntax differences or additional options, all algorithms from the given stage can be replaced in the code below. For explanation of all parameters and posibilities please consult the API Reference.

To fully understand the way ADA handles data from different processing stages, as well as for a comprehensive guide through the most important parameters and methods available within different data containers check the Data types section.

Data loading and epoching

Load the data, trim them by 1 hour from the start and 10 minutes from the end, and export to .ada file:

from ada.io.file_manager import FileManager
raw = FileManager.load_file('example.bin')
raw = raw.trim('01:00:00', '00:10:00')  # microseconds can be added after .
# you can use also cutting methods, e.g.:
raw_cutted = raw.cut_by_timestamp(raw.first_sample_timestamp + 3600, raw.last_sample_timestamp - 600)
FileManager.export_generic('trimmed.ada', raw_cutted)
# alternatively export to the native GeneActiv .csv
raw.export('trimmed.csv')

Collapse data into 30-s long epochs using Activity Index method, save already epoched file for futher use:

from ada.preprocessing.epocher import ActivityIndex
epocher = ActivityIndex(30)
epoched = epocher.to_epoch(raw)
epoched.export('epoched.ada')

Example of sleep scoring

Score the data using the universal filter, calculate some sleep quality metric, save scorings and full sleep report, and plot the summary figure:

from ada.short.unified import UFA
from ada.database_utils.summary import summary_sleep_report, plot
import matplotlib.pyplot as plt
scorer = UFA()  # if the automatic threshold interpolation is unavailable, pass the threshold as an argument, e.g. scorer = UFA(1)
scored = scorer.to_score(epoched)
print(scored.sleep_fragmentation_index())
scored.export('scored.ada')
summary_sleep_report([scored], 'report.csv')  # summary can sumarize info from multiple subjects
plot(epoched, scored, timestamp=False)
plt.show()

Example of long fitting

Using the previously epoched data we can fit the Hill-transformed cosinor to the data, plot the fit, save the results and summary:

from ada.long.cosinor import Hill
from ada.database_utils.summary import summary_long_report, plot
model = Hill()
result = model.fit(epoched)[0]  # list of results, in case of non-linear methods always with 1 element
result.plot(epoched)
plt.show()
# for cosinor specifically you may also produce a nicer plot with
# plot(epoched, None, result)
results.export('hill.ada.long')
summary_long_report([results], 'long_report.csv')  # same as in summary_sleep_report

We can also visualise daily activity profile of one or multiple recordings on a plot averaging data from few days:

from ada.database_utils.summary import daily_profile
daily_profile(epoched)
plt.show()
# you can also plot multiple subjects on one plot, like so:
# daily_profile([data_1, data_2, data_3])

Operating on PSG and actigraphic recordings

Assuming that you have PSG staging in the OBCI format, which was derived from PSG recorded in parallel to actigraphy, you can easily construct a synchronized ActiPSG object. Then, you can use them to e.g. fit scoring threshold to specific population.

from ada.io.filemanager import FileManager
from ada.short.unified import UFA
acti_psg = FileManager.load_ActiPSG_from_tags(path_to_acti, path_to_tag, path_to_xml)
...
# lets asume, that pgs_list is a list contatining multiple ActiPSG objects
ufa = UFA()
threshold_range = (0.1, 10)
ufa.fit_threshold(psg_list, threshold_range)

If you store PSG scorings in different format, then you can manually construct ActiPSG object using ActiPSG.from_continous_stages. Tags need to be provided as a list of dictionaries, with each dictionary corresponding to 1 tag. The tags have to be nonoverlapping and continous (i.e. without gaps between subsequent tags). The minimal tag should be constructed according to the following template:

tag = {'name': 'N1',
       'start_timestamp': 30,  # timestamps relative to the PSG start
       'end_timestamp': 60}

In both cases a built-in heuristic is used to convert staging into sleep/wake binary score. You can define your own converting function and pass it to the above-described methods if needed.