Skip to main content
`Ctrl`+`K`

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

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

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

     9from ada.preprocessing.epocher import ActivityIndex
    10epocher = ActivityIndex(30)
    11epoched = epocher.to_epoch(raw)
    12epoched.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:

    13from ada.short.unified import UFA
    14from ada.database_utils.summary import summary_sleep_report, plot
    15import matplotlib.pyplot as plt
    16scorer = UFA()  # if the automatic threshold interpolation is unavailable, pass the threshold as an argument, e.g. scorer = UFA(1)
    17scored = scorer.to_score(epoched)
    18print(scored.sleep_fragmentation_index())
    19scored.export('scored.ada')
    20summary_sleep_report([scored], 'report.csv')  # summary can sumarize info from multiple subjects
    21plot(epoched, scored, timestamp=False)
    22plt.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:

    23from ada.long.cosinor import Hill
    24from ada.database_utils.summary import summary_long_report, plot
    25model = Hill()
    26result = model.fit(epoched)[0]  # list of results, in case of non-linear methods always with 1 element
    27result.plot(epoched)
    28plt.show()
    29# for cosinor specifically you may also produce a nicer plot with
    30# plot(epoched, None, result)
    31results.export('hill.ada.long')
    32summary_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:

    33from ada.database_utils.summary import daily_profile
    34daily_profile(epoched)
    35plt.show()
    36# you can also plot multiple subjects on one plot, like so:
    37# 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.

    1from ada.io.filemanager import FileManager
    2from ada.short.unified import UFA
    3acti_psg = FileManager.load_ActiPSG_from_tags(path_to_acti, path_to_tag, path_to_xml)
    4...
    5# lets asume, that pgs_list is a list contatining multiple ActiPSG objects
    6ufa = UFA()
    7threshold_range = (0.1, 10)
    8ufa.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:

    1tag = {'name': 'N1',
    2       'start_timestamp': 30,  # timestamps relative to the PSG start
    3       '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.