feat: add options to enable/disable spurious sleep removal

Author: chanshing

src/accelerometer/accProcess.py

@@ -175,6 +175,15 @@ def main():  # noqa: C901
     parser.add_argument('--activityModel', type=str,
                         default="walmsley",
                         help="""trained activity model .tar file""")
+    parser.add_argument('--removeSpuriousSleep',
+                        metavar='True/False', default=True, type=str2bool,
+                        help="""Remove spurious sleep periods from the
+                            activity classification? (default : %(default)s)""")
+    parser.add_argument('--removeSpuriousSleepTol',
+                        metavar='mins', default=60, type=int,
+                        help="""Sleep tolerance in minutes. If `--removeSpuriousSleep`
+                            and a sleep streak is shorter than this, it will be replaced
+                            with sedentary activity (default : %(default)s)""")
 
     # circadian rhythm options
     parser.add_argument('--psd',
@@ -329,6 +338,7 @@ def deleteIntermediateFiles():
         endTime=args.endTime, epochPeriod=args.epochPeriod,
         stationaryStd=args.stationaryStd, minNonWearDuration=args.minNonWearDuration,
         mgCpLPA=args.mgCpLPA, mgCpMPA=args.mgCpMPA, mgCpVPA=args.mgCpVPA,
+        removeSpuriousSleep=args.removeSpuriousSleep, removeSpuriousSleepTol=args.removeSpuriousSleepTol,
         activityModel=args.activityModel,
         intensityDistribution=args.intensityDistribution,
         psd=args.psd, fourierFrequency=args.fourierFrequency,

src/accelerometer/classification.py

@@ -25,7 +25,9 @@ def activityClassification(
     activityModel: str = "walmsley", 
     mgCpLPA: int = 45,
     mgCpMPA: int = 100,
-    mgCpVPA: int = 400
+    mgCpVPA: int = 400,
+    spuriousSleepRemoval: bool = True,
+    spuriousSleepTol: int = 60,  # in minutes
 ):
     """
     Perform classification of activity states from epoch feature data. Based on
@@ -72,7 +74,8 @@ def activityClassification(
         del enmo
         del other
 
-    Y = removeSpuriousSleep(Y, activityModel=activityModel)
+    if spuriousSleepRemoval:
+        Y = removeSpuriousSleep(Y, activityModel=activityModel, sleepTol=spuriousSleepTol)
 
     # One-hot encoding
     epoch.loc[ok, labels] = (Y[ok].to_numpy()[:, None] == labels).astype('float')
@@ -334,13 +337,14 @@ def log(x):
     return viterbi_path
 
 
-def removeSpuriousSleep(Y, activityModel='walmsley', sleepTol='1H'):
+def removeSpuriousSleep(Y, activityModel='walmsley', sleepTol=60):
     """
     Remove spurious sleep epochs from activity classification.
 
     :param pandas.Series Y: Model output
     :param str activityModel: Model identifier
-    :param str sleepTol: Minimum sleep duration, e.g. '1H'
+    :param str sleepTol: Sleep tolerance in minutes. If a sleep streak is shorter 
+        than this, it will be replaced with sedentary activity.
 
     :return: Dataframe of revised model output
     :rtype: pandas.DataFrame
@@ -359,7 +363,7 @@ def removeSpuriousSleep(Y, activityModel='walmsley', sleepTol='1H'):
         .cumsum()
         .pipe(lambda x: x.groupby(x).transform('count') * sleep)
     )
-    sleepTol = pd.Timedelta(sleepTol) / Y.index.freq
+    sleepTol = pd.Timedelta(f"{sleepTol}min") / Y.index.freq
     whr = sleep & (sleepStreak < sleepTol)
     Y = Y.copy()  # no modify original
     Y.loc[whr] = newValue

src/accelerometer/summarisation.py

@@ -15,6 +15,7 @@ def getActivitySummary(  # noqa: C901
     startTime=None, endTime=None,
     epochPeriod=30, stationaryStd=13, minNonWearDuration=60,
     mgCpLPA=45, mgCpMPA=100, mgCpVPA=400,
+    removeSpuriousSleep=True, removeSpuriousSleepTol=60,
     activityModel="walmsley",
     intensityDistribution=False, imputation=True,
     psd=False, fourierFrequency=False, fourierWithAcc=False, m10l5=False
@@ -41,6 +42,8 @@ def getActivitySummary(  # noqa: C901
     :param int minNonWearDuration: Minimum duration of nonwear events (minutes)
     :param int mgCutPointMVPA: Milli-gravity threshold for moderate intensity activity
     :param int mgCutPointVPA: Milli-gravity threshold for vigorous intensity activity
+    :param bool removeSpuriousSleep: Remove spurious sleep epochs
+    :param int removeSpuriousSleepTol: Tolerance (in minutes) for spurious sleep removal
     :param str activityModel: Input tar model file which contains random forest
         pickle model, HMM priors/transitions/emissions npy files, and npy file
         of METS for each activity state
@@ -103,7 +106,12 @@ def getActivitySummary(  # noqa: C901
     # Predict activity from features, and add label column
     labels = []
     if activityClassification:
-        data, labels = classification.activityClassification(data, activityModel, mgCpLPA, mgCpMPA, mgCpVPA)
+        data, labels = classification.activityClassification(
+            data,
+            activityModel,
+            mgCpLPA, mgCpMPA, mgCpVPA,
+            removeSpuriousSleep, removeSpuriousSleepTol
+        )
 
     # Calculate empirical cumulative distribution function of vector magnitudes
     if intensityDistribution: