ActiWearCheck

evaluate days of valid wear for Fitbit activity trackers.

This repository contains:

• a software (actiwearcheck.py) to process HR or accelerometer minute data obtained from Fitbit devices and evaluate days of valid wear.
• sample data for 6 subjects, as extracted from Fitabase.

run actiwearcheck

python3 actiwearcheck.py [-d path_to_data] [-o path_to_output] [-c path_to_config]

• path_to_data: path to the fitbit data folder, e.g. .ActiWearCheck/samples/. If not provided, defaults to the current directory.
• path_to_output: path where the results will be saved. If not provided, defaults to the current directory.
• path_to_config: path to the configuration file for the analysis, provided in the yaml format. If not provided, defaults to conf/default_conf.yaml. See that file for an exaustive list of options. The default configuration works with Fitabase export files.

methods of evaluation

The current configuration file accepts 3 different methods for evaluation of valid wear. The criteria are as follows:

• "hr_continue": a minimum number of minutes with heart rate data is required. The suggested default configuration is looking for days with at least 600 minutes of hear rate data.
• "calories_continue": a minimum number of minutes with energy expenditure data above the resting metabolic rest is required. The suggested default configuration is looking for days with at least 600 minutes above the resting metabolic rate.
• "calories_hourly": a minimum of hours containing at least a given number of minutes with energy expenditure above the resting metabolic rate. The suggested default configuration is looking for days with at least 10 hours that contain at least 1 minute above the resting metabolic rate.

main options

• "steps": a minimum number of steps ("steps_param") is required to consider a day as valid.
• "minute_day": the ratio of minute data (steps and calories) resampled to day and daily data obtained from daily summarize files should be over a given decimal between 0 and 1 ("minute_day_param") to consider a day as valid.
• "waking": only minutes between 5:00 and 22:59 are considered for the evaluation.
• "synch_check": evaluate the validity of data based on the interval between two synchronization dates. Interval criteria, which depend on device specifications, can be found in ./ActiWearCheck/actiwearcheck/devices/20241015_devices.yaml.

full documentation (help)

method: 'hr_continue' (default), 'calories_continue', 'calories_hourly','all'
evaluate valid wear days,
if 'hr_continue', from the number of minutes with HR data found in daily data files. HR data files are used.
if 'calories_continue', from the number of minutes with EE above REE. Minute data files are used.
if 'calories_hourly', from the number of hours with a least a selected number of minutes with EE above REE minute. Minute data files are used.

hr_continue: int between 0 and 1440. (default = 600)
number of minutes to be used as evaluation criteria for the 'hr_continue' method.

calories_continue: int between 0 and 1440. (default = 600)
number of minutes to be used as evaluation criteria for the 'calories_continue' method.

calories_hourly: [int between 1 and 24, int between 1 and 60] (default = [10, 1])
number of hours and minute-per-hour to be used as evaluation criteria for the 'calories_hourly' method.

steps: boolean (default = True)
an option to evaluate valid wear based on the daily number of steps.

steps_param: int equal or higher than 0 (default = 1)
number of steps to be used as evaluation criteria when steps = True.

minute_day: boolean (default = True)
An option to evaluate valid wear based on the ratio of minute data (steps and calories) resampled to day and daily data obtained from daily summarize files.

minute day_param: float between 0.0 and 1.0 (default = 0.9)
ratio of difference between "per day" data, and "per minute" data resampled by day, to be used as evaluation criteria when  = True.

synch_check: boolean (default = False)
an option to evaluate the validity of data based on the interval between two synchronization dates.
the interval criteria depends on the device specifications (currently supported for the following devices: alta, alta hr and inspire 2).

waking: boolean (default = False)
if True, conduct the valid wear evaluation between 5:00 and 22:59 only.
cannot currenlty be used for method = 'hr_continue'

fitabase_suffixes:
string to be found in fitabase file names for hr, minute calories, daily calories, minutes steps, daily steps and synch data.

fitabase_series:
name of time series of interest for hr, calories, minute steps and daily steps data.

drop_na: boolean (default = True)
if True, remove days with no data.

subjectwise_output: boolean (default = True)
if True, results are saved in one file per subject.

output_basename: string (default = 'actiwear')
name of the output csv file.

debug: boolean (default = False)  
prints all steps and information to debug.