Introduction to pyActigraphy

This introduction notebook illustrates some basic functionalities of the pyActigraphy package:

• Reading files

• Inspecting the file header content

• Visualising the actigraphy data

First, load the pyActigraphy package:

import pyActigraphy

To display figures, the plotly package is used:

import plotly.graph_objects as go

How to read an individual actigraphy file

pyActigraphy reads several actigraphy file formats:

• agd (Actigraph)

• atr (ActTrust)

• awd (Actiwatch)

• bba (Axivity or GeneActiv via the Biobankaccelerometer package)

• dqt (DaqTix)

• mesa (MESA dataset, hosted by the NSRR)

• mtn (MotionWatch8)

• rpx (Respironics)

• tal (Tempatilumi)

For each file format, a dedicated function allows users to simply read in the file:

• read_raw_agd

• read_raw_atr

• read_raw_awd

• read_raw_bba

• read_raw_dqt

• read_raw_mesa

• read_raw_mtn

• read_raw_rpx

• read_raw_tal

For more infos, check the Python API

As an example, let’s read a .awd file located in the test directory of the pyActigraphy package:

import os
fpath = os.path.join(os.path.dirname(pyActigraphy.__file__),'tests/data/')

raw = pyActigraphy.io.read_raw_awd(fpath+'example_01.AWD')

This function simply returns an instance of the RawAWD class. Basically, it is an object that contains the data extracted from the actigraphy file.

In addition, this object has access to several methods that allow users to inspect the content of the file header.

NB: The other read_raw_XXX functions return the same kind of object. So the commands below remain valid, whatever the type of actigraphy file that is read.

How to retrieve header info

• Subject’s name:

raw.name

'example_01'

• Start time of the data acquisition:

raw.start_time

Timestamp('1918-01-23 13:58:00')

• Duration of the data acquisition:

raw.duration()

Timedelta('12 days 18:41:00')

• Serial number of the device:

raw.uuid

'V664055'

• Acquisition frequency:

raw.frequency

Timedelta('0 days 00:01:00')

How to plot the data

Several python packages are available to visualise data, such as Matplotlib or Bokeh.

Here, the package plotly is used as it provides an interactive viewer but feel free to use the package you prefer.

First, create a layout for the plot:

layout = go.Layout(
    title="Actigraphy data",
    xaxis=dict(title="Date time"),
    yaxis=dict(title="Counts/period"),
    showlegend=False
)

And then, simply plot the data:

go.Figure(data=[go.Scatter(x=raw.data.index.astype(str), y=raw.data)], layout=layout)

Daily activity profile

This activity profile is obtained by averaging the data over the consecutive days contained in the recording:

layout.update(title="Daily activity profile",xaxis=dict(title="Date time"), showlegend=False);

With pyActigraphy, you can easily control the resampling frequency (i.e. the resolution at which you want to inspect the data). It is also possible to binarize the data: 0 for inactive or 1 for active.

help(raw.average_daily_activity)

Help on method average_daily_activity in module pyActigraphy.metrics.metrics:

average_daily_activity(freq='5min', cyclic=False, binarize=True, threshold=4, time_origin=None, whs='1h') method of pyActigraphy.io.awd.awd.RawAWD instance
    Average daily activity distribution

    Calculate the daily profile of activity. Data are averaged over all the
    days.

    Parameters
    ----------
    freq: str, optional
        Data resampling frequency.
        Cf. #timeseries-offset-aliases in
        <https://pandas.pydata.org/pandas-docs/stable/timeseries.html>.
    cyclic: bool, optional
        If set to True, two daily profiles are concatenated to ensure
        continuity between the last point of the day and the first one.
        Default is False.
    binarize: bool, optional
        If set to True, the data are binarized.
        Default is True.
    threshold: int, optional
        If binarize is set to True, data above this threshold are set to 1
        and to 0 otherwise.
    time_origin: str or pd.Timedelta, optional
        If not None, origin of the time axis for the daily profile.
        Original time bins are translated as time delta with respect to
        this new origin.
        Default is None
        Supported time string: 'AonT', 'AoffT', any 'HH:MM:SS'
    whs: str, optional
        Window half size parameter for the detection of the activity
        onset/offset time. Relevant only if time_origin is set to
        'AonT' or AoffT'.
        Default is '1h'.

    Returns
    -------
    raw : pandas.Series
        A Series containing the daily activity profile with a 24h index.

daily_profile = raw.average_daily_activity(freq='15min', cyclic=False, binarize=False)

go.Figure(data=[
    go.Scatter(x=daily_profile.index.astype(str), y=daily_profile)
], layout=layout)

Activity onset and offset times

Based on this profile, it is possible to infer the mean activity onset and offset times (i.e. transition time between rest and activity states).

For more info, check the online documentation: AonT, AoffT

raw.AonT(freq='15min', binarize=True)

Timedelta('0 days 07:00:00')

raw.AoffT(freq='15min', binarize=True)

Timedelta('0 days 19:30:00')