README.md

Sleep Pattern Analysis App (SPAA)

An awesome application to analyze your sleep data and export it! (FHIR compatable)

Visit App · View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Usage
   • Checking Capabilities
   • Using provided test data
   • Using your own data
3. Roadmap
   • Project Timeline
   • Extra features added
   • Future scope
4. Project Artifacts
   • Screen Mockups vs Current Webpage
   • Architecture Diagram
   • Sleep Data Calculations
5. Contact

About The Project

Sleep is one of the fundamental needs of the human body. It directly affects our physical and mental health. It’s not only important to have the required amount of hours of sleep but it’s also important to have quality sleep. While some people thrive on having a long 8-hour sleep session, others function better when taking naps during the day and a shorter 6-hour sleep session at night. The sleep needs of each individual differ according to their body. It is only by tracking and analyzing the sleep data, we can come to know if these needs are fulfilled properly. The main aim of the Sleep Pattern Analysis App (SPAA) is to make the user aware of which sleeping pattern works best for them.

While there are a lot of tools on the market that track and report sleep data (Android Apps, Smartwatches, Fitness Trackers, etc), very few of them provide some analysis of the sleep data. They inform the user on how long they have slept and in which stage (REM, deep, etc), but they don’t provide information regarding the quality of the sleep, recovery, sleep debt, etc. A lot of the apps also gatekeep information behind paywalls.

The Sleep Pattern Analysis App (SPAA) empowers users by providing them with a detailed analysis of their sleeping patterns to help them make informed decisions. It allows users to import their weekly/monthly data in JSON format, clean and visualize the data, and provide the user with a calculated sleep score along with some recommendations (continue sleep pattern, recovery hours, etc.)

Built With

• 
• 
• 
• 
• fhir.resources library
• Deployed on

(back to top)

Usage

Checking capabilities

When you open the webpage simply click on the button Sample Data.

Using provided test data

There are 4 data files located in the folder sample_import_data. Each file includes about 1-month worth of real sleep data I have expoted from my Fitbit accout.

Using your own data

First fetch your own data using the steps mentioned below. Then click on the Import button and upload your .json file to view the analysis.

How to import your sleep data from FitBit.

1. Login to the Fitbit dashboard using your Fitbit ID or using Google SSO
2. Click on the settings icon on the top right
3. From the left side menu click on "Data Export"
4. Next under "Select data to include" - select Fitbit, then choose the TXT/CSV/JSON format and click on "Next Step".
5. Choose the folowing settings (adjust as required) -
   • Destination - Send download link via email
   • Frequency - Export Once
   • File type - .zip
   • File size - 2 GB
6. Finally click on "Create export". Depending on the size it can take anywhere between 2 to 24 hours to receive the dowload link.
7. Download the .zip file
8. Navigate to Takeout -> Fitbit -> Global Export Data
9. You can select any file starting with the string "sleep-". e.g. "sleep-2023-12-29.json" to upload and use with SPAA

(back to top)

Roadmap

Project Timeline

Sprint #	Week #	Start Date	End Date	Tasks
1	1-6	22nd Jan	1st Feb	Team Formation and Kickoff
2	7	2nd Feb	25th Feb	Project Planning and Design
3	8	26th Feb	3rd March	Project Setup
	9	4th Mar	10th Mar	Import Feature
	10	11th Mar	17th Mar	Data Cleaning + Processing
4	11	18th Mar	24th March	Sleep Score Engine
	12	25th Mar	31th March	Sleep Score Engine
5	13	1st Apr	7th Apr	Data Visualizations
	14	8th Apr	14th Apr	Export Feature + Cleanup
6	15	15th Apr	21st Apr	Testing + Documentation + Final Submission

Detailed tasks completed in each week

Week #	Accomplishments for the week
1-7	Team Formation and Kickoff Project Planning and Design
8-9	Learning React and JS Research about sleep in general Setting up project Base React code setup GitHub Pages deployment setup Resolving issues with deployment Basic homepage visuals Import JSON feature + it’s deployment
10	Learning React and JS Research around sleep stages and calculations possible for the available data. Data cleaning and processing Checks for invalid JSONs Calculation of fields like duration, timeInBed, efficiency, etc. Identifying and calculating the level of sleep (deep, light, etc.) from the main data array. Documentation of above calculation formulas (50% done) GitHub Pages deployment maintenance.
11	Research for sleep engine (sleep stages + calculations) Started work on sleep engine (scoring) calculations. Updated formulas for calculating efficiency more accurately. Updated formulas for calculating duration (using 2 methods) and added an error check for >5%. Updated JSON processing (part of code cleanup) Added proper error handling code (part of code cleanup) Updated console logs for better debugging (part of code cleanup)
12	Research for sleep engine (specifically regarding sleep stages) Completing work on sleep engine (scoring) calculations. Rectifying issues with sleep engine logic. (majority time went here) GitHub Pages deployment maintenance. Preparation for the next sprint - Learning about data visualizations and exploring its available libraries.
13	Spent time exploring and learning React graph libraries. Tried a few but some of them did not have the customization I was looking for. Finally settled on using the 'recharts' library. Most of the time was spent experimenting with the data and graphs. Spent some more time modifying the data processing functions as we needed the data in a particular format to give as input for the graphs. Also added the sample data button which is supposed to pick up some sample data to show to the user (currently under progress) (extra feature) A lot of visual changes + CSS (like choosing color schemes, graph layout, etc.)
14	Export as a FHIR importable resource (export button feature). Show/Hide processed JSON data button. Updating graph visuals (using more complex graphs). Fixed/Updated some calculations (avg sleep debt, sleep phase percentage, etc.). GitHub Pages deployment maintenance and checks for final deployment. Preparation for the next sprint - started work on documentation.

Extra features added

• Reactive Graphs
• Sample Data Button
• Show/Hide processed JSON data button

Future scope

• Enhanced Exports - More customizations (FHIR compatible) for the export feature.
• Enhanced Visualization - Adding more interactive and customizable visualization options.
• Google SSO Login - for quick and easy access to import the data.
• Enhanced compatibility - Add support to directly import data from the Fitbit APIs, as well as integration and support with Apple Health and Garmin.
• Integration with Wearable Devices - Integrating with wearable devices to directly import sleep data, providing real-time insights and personalized recommendations.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Project Artifacts

Screen Mockups vs Current Webpage

vs

Architecture Diagram

Sleep Data Calculations

1. Calculate Levels Summary:
   • Formula: Calculate the count and total minutes for each sleep stage (deep, light, rem, wake) from the levels data.
   • Function: calculateLevelsSummary(sleepData)
2. Calculate Duration:
   • Formula: Calculate sleep duration using two methods:
     • By subtracting endTime from startTime.
     • By summing the minutes of each sleep stage.
   • Function: calculateDuration(sleepData)
3. Calculate Time in Bed:
   • Formula: If timeInBed is not provided, calculate it using sleep duration.
   • Function: calculateTimeInBed(sleepData)
4. Calculate Efficiency:
   • Formula: Calculate sleep efficiency as the ratio of total sleep time to time in bed.
   • Function: calculateEfficiency(sleepData, levelsSummary)
5. Calculate Sleep Metrics:
   • Formula: If minutesAsleep and minutesAwake are not provided, calculate them using the sum of minutes for each sleep stage.
   • Function: calculateSleepMetrics(sleepData, levelsSummary)
6. Calculate Sleep Score:
   • Formula: Calculate sleep score based on duration, sleep stages (deep, light, rem), and efficiency.
   • Function: calculateSleepScore(sleepData, duration, timeInBed, levelsSummary, efficiency, minutesAsleep, minutesAwake)
7. Calculate Duration Factor:
   • Formula: Normalize sleep duration between 7 to 8 hours and calculate a factor based on how close it is to the ideal range.
   • Function: calculateDurationFactor(duration)
8. Calculate Sleep Phase Factor:
   • Formula: Calculate a factor based on the percentage of time spent in a specific sleep phase compared to the total sleep time.
   • Function: calculateSleepPhaseFactor(phaseMinutes, totalMinutes, targetPercentage)
9. Calculate Overall Summary:
   • Formula: Calculate average sleep score, efficiency, hours slept, sleep debt, and sleep stage percentages per day.
   • Function: calculateOverallSummary(jsonData)

Contact

Vatsal Paresh Unadkat - [email protected] Project Link: https://github.gatech.edu/vunadkat6/sleep-pattern-analysis

(back to top)