Merge pull request #121 from ghammad/develop

Develop

README.rst

@@ -24,14 +24,23 @@ This package is meant to provide a comprehensive set of tools to:
 * read native actigraphy data files with various formats:
 
   * Actigraph: wGT3X-BT
-  * CamNtech: Actiwatch 4 and MotionWatch 8
+  * CamNtech: Actiwatch 4, 7, L(-Plus) and MotionWatch 8
   * Condor Instrument: ActTrust 2
   * Daqtix: Daqtometer
   * Respironics: Actiwatch 2 and Actiwatch Spectrum (plus)
   * Tempatilumi (CE Brasil)
 
 ..
 
+* **NEW** read actigraphy data format from the `MESA dataset <https://sleepdata.org/datasets/mesa>`_, hosted by the `National Sleep Research Resource <https://sleepdata.org>`_.
+
+* **NEW** read actigraphy data files produced by the `accelerometer <https://biobankaccanalysis.readthedocs.io/en/latest/index.html>`_ package that can be used to calibrate and convert raw accelerometer data recorded with:
+
+  * Axivity: AX3, device used by UK Biobank,
+  * Activinsights: GENEActiv, used by the Whitehall II study.
+
+..
+
 * **NEW** read light exposure data recorded by the aforementioned devices (when available)
 
 * clean the raw data and mask spurious periods of inactivity

docs/source/ActivityReport.rst

@@ -0,0 +1,20 @@
+====================
+ActivityReport class
+====================
+
+.. contents:: Table of Contents
+    :local:
+    :depth: 2
+
+.. currentmodule:: pyActigraphy.reports.ActivityReport
+.. autoclass:: pyActigraphy.reports.ActivityReport
+
+   .. rubric:: Activity report
+   .. autosummary::
+       :toctree: _autosummary/
+
+       cut_points
+       labels
+       results
+       fit
+       pretty_results

docs/source/api.rst

@@ -17,11 +17,13 @@ Uniform API to read multiple actigraphy data formats.
 Currently, the supported formats are:
 
 * wGT3X-BT, Actigraph (.agd file format only);
-* Actiwatch 4 and MotionWatch 8, CamNtech (.awd and .mtn);
+* Actiwatch 4, 7, L(-Plus) and MotionWatch 8, CamNtech (.awd and .mtn);
 * ActTrust 2, Condor Instruments (.txt);
 * Daqtometer, Daqtix (.csv);
 * Actiwatch 2 and Actiwatch Spectrum Plus, Philips Respironics (.csv)
 * Tempatilumi (CE Brasil)
+* MESA dataset file format
+* Biobankaccelerometer file format (BBA)
 
 Associated functions:
 
@@ -34,7 +36,9 @@ Associated functions:
    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
@@ -77,6 +81,12 @@ Rest-Activity Rhythms
 * Non-parametric and transition probability methods: :mod:`pyActigraphy.metrics.MetricsMixin`
 
 
+Rest and Activity reports
+=========================
+
+* Activity report: :mod:`pyActigraphy.reports.ActivityReport`
+
+
 Rest-activity scoring and sleep diary
 =====================================
 

docs/source/changelog.rst

@@ -8,6 +8,18 @@ What's new
 
 *************
 
+v1.2 ("Let's go 3D", March 2023)
+-------------------------------------------
+
+This release contains new features:
+
+* Activity reports: summary statistics about time spent above user-defined activity cut points (See `pyActigraphy.io.BaseRaw.create_activity_report <https://ghammad.github.io/pyActigraphy/BaseRaw.html#pyActigraphy.io.BaseRaw.create_activity_report>`_ function).
+* Biobank Accelerometer Analysis file format: new reader function for files generated by the 'accelerometer' package that reads, calibrates and processes raw accelerometer data from Axivity AX3 and Activinsights GeneActiv devices (see `pyActigraphy.io.read_raw_bba <https://ghammad.github.io/pyActigraphy/_autosummary/pyActigraphy.io.read_raw_bba.html#pyActigraphy.io.read_raw_bba>`_ function).
+* Actiwatch (CamNtech) file format: support for files acquired with various Actiwatch models (Actiwatch 4, 7, L(-Plus), Mini, I(nsonmia), T(emperature))
+* Actigraph AGD reader: light channel handled with pyLight, if available.
+
+*************
+
 v1.1 ("There shall be light", January 2023)
 -------------------------------------------
 

pyActigraphy/__init__.py

@@ -21,6 +21,7 @@
 from . import light
 from . import metrics
 from . import recording
+from . import reports
 from . import sleep
 from . import utils
 from . import tests
@@ -33,10 +34,11 @@
     "light",
     "metrics",
     "recording",
+    "reports",
     "sleep",
     "tests",
     "utils",
     "viz"
 ]
 
-__version__ = '1.1'
+__version__ = '1.2'

pyActigraphy/io/__init__.py

@@ -15,6 +15,7 @@
 from .agd import read_raw_agd
 from .atr import read_raw_atr
 from .awd import read_raw_awd
+from .bba import read_raw_bba
 from .dqt import read_raw_dqt
 from .mesa import read_raw_mesa
 from .mtn import read_raw_mtn
@@ -27,6 +28,7 @@
     "read_raw_agd",
     "read_raw_atr",
     "read_raw_awd",
+    "read_raw_bba",
     "read_raw_dqt",
     "read_raw_mesa",
     "read_raw_mtn",

pyActigraphy/io/agd/agd.py

@@ -5,6 +5,7 @@
 import warnings
 
 from ..base import BaseRaw
+from pyActigraphy.light import LightRecording
 
 
 class RawAGD(BaseRaw):
@@ -57,6 +58,7 @@ def __init__(
             int(settings.at['epochlength', 'settingValue']),
             unit='s'
         )
+        self.__model = settings.at['devicename', 'settingValue']
 
         # extract proximity (wear/no-wear) informations
         try:
@@ -136,6 +138,7 @@ def __init__(
 
         # call __init__ function of the base class
         super().__init__(
+            fpath=input_fname,
             name=name,
             uuid=uuid,
             format='AGD',
@@ -144,7 +147,12 @@ def __init__(
             period=period,
             frequency=freq,
             data=data['mag'],
-            light=data['lux'] if 'lux' in data.columns else None
+            light=LightRecording(
+                name=name,
+                uuid=uuid,
+                data=data['lux'].to_frame(name='whitelight'),
+                frequency=data.index.freq
+            ) if 'lux' in data.columns else None
         )
 
         # Close sqlite3 connection
@@ -156,6 +164,22 @@ def __extract_position(self, column):
         else:
             return None
 
+    def __extract_light_channel(self, channel):
+        if self.light is None:
+            return None
+        else:
+            return self.light.get_channel(channel)
+
+    @property
+    def white_light(self):
+        r"""White light levels (in lux.)"""
+        return self.__extract_light_channel("whitelight")
+
+    @property
+    def model(self):
+        r"""Model of the device: devicename"""
+        return self.__model
+
     @staticmethod
     def __to_timestamps(ticks):
         return pd.to_datetime(

pyActigraphy/io/atr/atr.py

@@ -123,6 +123,7 @@ def __init__(
 
         # call __init__ function of the base class
         super().__init__(
+            fpath=input_fname,
             name=name,
             uuid=uuid,
             format='ATR',