This is a Python package that automate Fitbit OAuth2 authorisation and collect sleep, activity and heart rate data from fitbit devices
- OAth2-based Fitbit authentication (per participant)
- Participant information supplied in a CSV file
- Device-to-participant assignment and session tracking
- Sleep, activity and heart rate data collection
- Save Sleep, activity and heart rate to csv
FitbitDataPipeline
- fitbit_pipeline
- Classes
- runner
- Utility
- logs/ # application logs
- processed_data: Folder containing the pipeline output - Sleep Summary, Sleep Staging, Activity and Heartrate data
- raw_sleep_data : raw sleep json file from Fitbit Web API
- tokens : Locally managed Fitbit user tokens
- app_server - Flask app for the Fitbit OAuth2
- auth_code - Application generated for the exchange of the redirect url after authentication
- config - contain some user configurations and fitbit WebAPI endpoint URLs
- License
- participants.csv
- readme - This file
- requirements : Required packages to successfully run the application
Aside the packages required as specified in the requirements file. The following are also needed to run this pipeline
- Core - Python 3.8+
- Fitbit developer account
- API client ID and secret (ensure intraday data access is enabled using require a separate application)
- Clone the repository
git clone https://github.com/sleepdetectives/fitbit-data-pipeline.git
cd FitbitDataPipeline
- Set up a virtual environment (Optional)
python -m venv venv
source venv/bin/activate
- Install Dependencies
pip install -r requirements.txt
- Create a new project or use an existing one
- Head on to your terminal to install the package
pip install fitbit-data-pipeline
- Install poetry package based on your platform(OS)
- After performing the preparing environment and configuration steps (See below):
- Start the app_server using
poetry run fitbit-auth
- Start the main data collection process
poetry run fitbit-app
- Add the participant file (participants.csv) to the project root folder with the following structure:
############# participants file ##################################
pid,age,fitbit_id,device_model,study_period,collection_dates
ABC02,10,Z4XX11,Inspire 3,"2024-11-05,2024-11-13",2024-11-05;2024-11-06;2024-11-07;2024-11-08;2024-11-09;2024-11-10;2024-11-11;2024-11-12;2024-11-13
###################################################################
- create .env file in the project root and populate it with your fitbit developer account client id and secret
############### .env file ###################################
client_id = "XXXXX" client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
##############################################################
- Create a copy of sample_files\config.py file and place in the project root folder
Note: sample files needed for the above are included in the "sample_files" directory
- all_sleep_data :
....fig 1
The light green background columns are out-of-the-box while the light blue category are derived. Detailed as follows:
SOL - I looked at first sleep staging , if the first sleep staging is wake then followed by any of light, deep or REM then there is SOL, otherwise, no SOL
.....fig 2
WASO = MinutesAwake - SOL (Fitbit claimed that raw minutes awake does not include awake before first sleep episode or after wakeup) - sleep_time - From fig 2 above the sample from the left had the SOL hence differentiating "StartTime" from "sleep_time"
- wake_time - Checking the last two entry in the sleep staging could give an idea of actual wake time. If the last episode is wake, most likely, the participant spend some time in bed after wake
- TST = time_diff(sleep_time, wake_time) - WASO
- SE = TST/TimeInBed * 100 Note: Fitbit advised that only SE from "classic log type" is valid and this should be ignored for stages log type (even though a value will be provided)
This project is licensed under the MIT License
Pull request are highly welcome! Please open an issue first to discuss your idea
For questions or support, reach out to: abiola.saka@bristol.ac.uk or sakbioonline@gmail.com