Type:	Package
Title:	'Fitbit' Visualizations
Version:	1.0.8
Date:	2026-04-27
Maintainer:	Lampros Mouselimis <mouselimislampros@gmail.com>
URL:	https://github.com/mlampros/fitbitViz, https://mlampros.github.io/fitbitViz/
Description:	Visualization of pre-downloaded 'Fitbit' personal health data using 'ggplot2' Visualizations, 'Leaflet' and 3-dimensional 'Rayshader' Maps. The 3-dimensional 'Rayshader' Map requires the installation of the 'CopernicusDEM' R package which includes the 30- and 90-meter elevation data.
License:	GPL-3
Encoding:	UTF-8
Depends:	R(≥ 3.5)
Imports:	glue, ggplot2, lubridate, patchwork, data.table, stats, viridis, scales, ggthemes, paletteer, XML, hms, leaflet, sf, rstudioapi, grDevices, leafgl, raster (≥ 3.6-3), terra, magrittr, utils, lifecycle, reshape2
Suggests:	CopernicusDEM, testthat (≥ 3.0.0), knitr, rmarkdown, DT, rgl, rayshader, magick
RoxygenNote:	7.3.2
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-04-27 08:05:07 UTC; lampros
Author:	Lampros Mouselimis [aut, cre]
Repository:	CRAN
Date/Publication:	2026-04-27 08:50:03 UTC

The GPS-TCX data as a formated data.table

Description

The GPS-TCX data as a formated data.table

Usage

GPS_TCX_data(tcx_file, time_zone = "Europe/Athens", verbose = FALSE)

Arguments

Value

either NULL or an object of class data.table

Examples

## Not run: 

require(fitbitViz)

# export the TCX file from the Fitbit website or app for the desired activity
# then pass the file path to GPS_TCX_data()

res_tcx <- GPS_TCX_data(
  tcx_file = "/path/to/activity.tcx",
  time_zone = "Europe/Athens",
  verbose = TRUE
)
str(res_tcx)

## End(Not run)

elapsed time in hours & minutes & seconds

Description

elapsed time in hours & minutes & seconds

Usage

compute_elapsed_time(time_start)

Arguments

Value

It does not return a value but only prints the time in form of a character string in the R session

Function to crop the AOI from the downloaded DEM .tif file

Description

Function to crop the AOI from the downloaded DEM .tif file

Usage

crop_DEM(tif_or_vrt_dem_file, sf_buffer_obj, verbose = FALSE)

Arguments

Value

an object of class SpatRaster

Examples

## Not run: 

require(fitbitViz)

# export the TCX file from the Fitbit website or app for the desired activity

res_tcx <- GPS_TCX_data(
  tcx_file = "/path/to/activity.tcx",
  time_zone = "Europe/Athens",
  verbose = TRUE
)
str(res_tcx)

# ....................................................
# then compute the sf-object buffer and raster-extend
# ....................................................

sf_rst_ext <- extend_AOI_buffer(
  dat_gps_tcx = res_tcx,
  buffer_in_meters = 1000,
  CRS = 4326,
  verbose = TRUE
)
sf_rst_ext

# ...............................................................
# Download the Copernicus DEM 30m elevation data because it has
# a better resolution, it takes a bit longer to download because
# the .tif file size is bigger
# ...............................................................

dem_dir <- tempdir()
# dem_dir

dem30 <- CopernicusDEM::aoi_geom_save_tif_matches(
  sf_or_file = sf_rst_ext$sfc_obj,
  dir_save_tifs = dem_dir,
  resolution = 30,
  crs_value = 4326,
  threads = parallel::detectCores(),
  verbose = TRUE
)

TIF <- list.files(dem_dir, pattern = ".tif", full.names = T)
# TIF

if (length(TIF) > 1) {
  # ....................................................
  # create a .VRT file if I have more than 1 .tif files
  # ....................................................

  file_out <- file.path(dem_dir, "VRT_mosaic_FILE.vrt")

  vrt_dem30 <- create_VRT_from_dir(
    dir_tifs = dem_dir,
    output_path_VRT = file_out,
    verbose = TRUE
  )
}

if (length(TIF) == 1) {
  # ..................................................
  # if I have a single .tif file keep the first index
  # ..................................................

  file_out <- TIF[1]
}

raysh_rst <- crop_DEM(
  tif_or_vrt_dem_file = file_out,
  sf_buffer_obj = sf_rst_ext$sfc_obj,
  verbose = TRUE
)

terra::plot(raysh_rst)

## End(Not run)

Extract the sf-object and raster extent based on a buffer (in meters)

Description

Extract the sf-object and raster extent based on a buffer (in meters)

Usage

extend_AOI_buffer(
  dat_gps_tcx,
  buffer_in_meters = 1000,
  CRS = 4326,
  verbose = FALSE
)

Arguments

Details

To create the buffer in meters using the 'sf' package I had to transform to another projection - by default I've used 7801 - as suggested in the following stackoverflow thread, https://stackoverflow.com/a/54754935/8302386

Value

an object of class list

Examples

## Not run: 

require(fitbitViz)

# export the TCX file from the Fitbit website or app for the desired activity

res_tcx <- GPS_TCX_data(
  tcx_file = "/path/to/activity.tcx",
  time_zone = "Europe/Athens",
  verbose = TRUE
)
str(res_tcx)

# ....................................................
# then compute the sf-object buffer and raster-extend
# ....................................................

sf_rst_ext <- extend_AOI_buffer(
  dat_gps_tcx = res_tcx,
  buffer_in_meters = 1000,
  CRS = 4326,
  verbose = TRUE
)
sf_rst_ext

## End(Not run)

Process pre-downloaded Fitbit data for Blood Oxygen Saturation, Heart Rate Variability, Breathing Rate, Temperature and Cardio Fitness Score (or VO2 Max) by Date

Description

Process pre-downloaded Fitbit data for Blood Oxygen Saturation, Heart Rate Variability, Breathing Rate, Temperature and Cardio Fitness Score (or VO2 Max) by Date

Usage

fitbit_data_type_by_date(data, type = "spo2", plot = FALSE)

Arguments

Details

'spo2' (Blood Oxygen Saturation)

This endpoint returns the SpO2 intraday data for a single date. SpO2 applies specifically to a user's "main sleep", which is the longest single period of time asleep on a given date. Spo2 values are calculated on a 5-minute exponentially-moving average

'hrv' (Heart Rate Variability)

This endpoint returns the Heart Rate Variability (HRV) intraday data for a single date. HRV data applies specifically to a user's "main sleep", which is the longest single period of time asleep on a given date. It measures the HRV rate at various times and returns Root Mean Square of Successive Differences (rmssd), Low Frequency (LF), High Frequency (HF), and Coverage data for a given measurement. Rmssd measures short-term variability in your heart rate while asleep. LF and HF capture the power in interbeat interval fluctuations within either high frequency or low frequency bands. Finally, coverage refers to data completeness in terms of the number of interbeat intervals

'br' (Breathing Rate)

This endpoint returns intraday breathing rate data for a specified date. It measures the average breathing rate throughout the day and categories your breathing rate by sleep stage. Sleep stages vary between light sleep, deep sleep, REM sleep, and full sleep

'temp' (Temperature)

This endpoint returns the Temperature (Skin) data for a single date. It only returns a value for dates on which the Fitbit device was able to record Temperature (skin) data. Temperature (Skin) data applies specifically to a user's "main sleep", which is the longest single period of time asleep on a given date

'cardioscore' (Cardio Fitness Score or VO2 Max)

The Cardio Fitness Score (also known as VO2 Max) endpoints are used for querying the maximum or optimum rate at which the user's heart, lungs, and muscles can effectively use oxygen during exercise

If the 'type' parameter is one of 'spo2' or 'hrv' and the 'plot' parameter is set to TRUE then the results will appear as a line plot. In case of 'hrv' a multiplot with the following variables will be displayed:

'rmssd'

The Root Mean Square of Successive Differences (RMSSD) between heart beats. It measures short-term variability in the user's heart rate in milliseconds (ms)

'coverage'

Data completeness in terms of the number of interbeat intervals

'hf'

The power in interbeat interval fluctuations within the high frequency band (0.15 Hz - 0.4 Hz)

'lf'

The power in interbeat interval fluctuations within the low frequency band (0.04 Hz - 0.15 Hz)

Value

a data.frame

References

https://dev.fitbit.com/build/reference/web-api/intraday/get-spo2-intraday-by-date/

https://dev.fitbit.com/build/reference/web-api/intraday/get-hrv-intraday-by-date/

https://dev.fitbit.com/build/reference/web-api/intraday/get-br-intraday-by-date/

https://dev.fitbit.com/build/reference/web-api/temperature/get-temperature-skin-summary-by-date

https://dev.fitbit.com/build/reference/web-api/cardio-fitness-score/get-vo2max-summary-by-date/

Examples

## Not run: 

require(fitbitViz)

# 'spo2_data' is the parsed JSON list from the Fitbit SpO2 intraday endpoint for a single date
# (i.e. the result of jsonlite::fromJSON() on the API response for that date)

res_type <- fitbit_data_type_by_date(
  data = spo2_data,
  type = "spo2",
  plot = TRUE
)
res_type

## End(Not run)

plot function for a single day (heart rate)

Description

plot function for a single day (heart rate)

Usage

ggplot_each_date(date_intraday, date)

Arguments

Value

a plot object of class ggplot2

Convert the GPS, TCX data to a LINESTRING

Description

Convert the GPS, TCX data to a LINESTRING

Usage

gps_lat_lon_to_LINESTRING(
  dat_gps_tcx,
  CRS = 4326,
  verbose = FALSE,
  time_split_asc_desc = NULL
)

Arguments

Details

Separate the Ascending and Descending coordinate points into 2 groups and give a different color to the Ascending and Descending routes

Value

an object of class list

Examples

## Not run: 

require(fitbitViz)

# export the TCX file from the Fitbit website or app for the desired activity

res_tcx <- GPS_TCX_data(
  tcx_file = "/path/to/activity.tcx",
  time_zone = "Europe/Athens",
  verbose = TRUE
)
str(res_tcx)


# ..................................................................
# By using using the maximum altitude as a split point of the route
# ..................................................................

linestring_dat_init <- gps_lat_lon_to_LINESTRING(
  dat_gps_tcx = res_tcx,
  CRS = 4326,
  time_split_asc_desc = NULL,
  verbose = TRUE
)

# .................................................................
# By using a customized split of the route (ascending, descending)
# .................................................................

linestring_dat_lubr <- gps_lat_lon_to_LINESTRING(
  dat_gps_tcx = res_tcx,
  CRS = 4326,
  time_split_asc_desc = lubridate::hms("17:05:00"),
  verbose = TRUE
)

## End(Not run)

Heart Rate Intraday Heatmap (by extracting the 'min.', 'median' and 'max.' values of the day)

Description

Heart Rate Intraday Heatmap (by extracting the 'min.', 'median' and 'max.' values of the day)

Usage

heart_rate_heatmap(heart_rate_intraday_data, angle_x_axis = 0)

Arguments

Value

a plot object of class ggplot2

Examples

## Not run: 

require(fitbitViz)

# ...........................................
# first compute the heart rate intraday data
# ...........................................

USER_ID <- "99xxxx"
token <- "my_long_web_api_token"

heart_dat <- heart_rate_time_series(
  user_id = USER_ID,
  token = token,
  date_start = "2021-03-09",
  date_end = "2021-03-16",
  time_start = "00:00",
  time_end = "23:59",
  detail_level = "1min",
  ggplot_intraday = TRUE,
  verbose = TRUE,
  show_nchar_case_error = 135
)

# ..........................................
# use the heart-rate-intraday data as input
# to the 'heart_rate_heatmap' function
# ..........................................

hrt_heat <- heart_rate_heatmap(
  heart_rate_intraday_data = heart_dat$heart_rate_intraday,
  angle_x_axis = 0
)
hrt_heat

## End(Not run)

heart rate activity time series

Description

heart rate activity time series

Usage

heart_rate_time_series(
  heart_rate_intraday_list,
  heart_rate = NULL,
  detail_level = "1min",
  ggplot_intraday = FALSE,
  ggplot_ncol = NULL,
  ggplot_nrow = NULL,
  verbose = FALSE
)

Arguments

Value

an object of class list

Examples

## Not run: 

require(fitbitViz)

# load pre-downloaded intraday heart rate data (one data.table per day, named by date)
# heart_rate_intraday_list is a named list where each element has columns 'time' and 'value'

heart_dat <- heart_rate_time_series(
  heart_rate_intraday_list = heart_rate_intraday_list,
  heart_rate = heart_rate_daily,
  detail_level = "1min",
  ggplot_intraday = TRUE,
  verbose = TRUE
)
heart_dat$plt
heart_dat$heart_rate
heart_dat$heart_rate_intraday

## End(Not run)

Heart Rate Variability during Sleep Time (the root mean square of successive differences)

Description

'r lifecycle::badge("deprecated")'

This function was deprecated, so please use the 'fitbit_data_type_by_date()' function instead with the 'type' parameter set to 'hrv' (Heart Rate Variability). See the documentation and the example section of the 'fitbit_data_type_by_date()' function for more details.

Usage

heart_rate_variability_sleep_time(
  heart_rate_data,
  sleep_begin = "00H 40M 0S",
  sleep_end = "08H 00M 0S",
  ggplot_hr_var = TRUE,
  angle_x_axis = 45
)

Arguments

Details

I use the '1min' rather than the '1sec' interval because it is consistent (it shows the 1-minute differences), whereas in case of '1sec' the difference between observations varies between 1 second and less than 60 seconds

This function calculates the root mean square of successive differences (RMSSD) and a higher heart rate variability is linked with better health

Based on the Fitbit application information weblink and the Wikipedia article (https://en.wikipedia.org/wiki/Heart_rate_variability) the heart rate variability is computed normally in ms (milliseconds)

Value

an object of class list

Examples

## Not run: 

require(fitbitViz)

# ...........................................
# first compute the heart rate intraday data
# ...........................................

USER_ID <- "99xxxx"
token <- "my_long_web_api_token"

heart_dat <- heart_rate_time_series(
  user_id = USER_ID,
  token = token,
  date_start = "2021-03-09",
  date_end = "2021-03-16",
  time_start = "00:00",
  time_end = "23:59",
  detail_level = "1min",
  ggplot_intraday = TRUE,
  verbose = TRUE,
  show_nchar_case_error = 135
)

# .......................
# heart rate variability
# .......................

hrt_rt_var <- heart_rate_variability_sleep_time(
  heart_rate_data = heart_dat,
  sleep_begin = "00H 40M 0S",
  sleep_end = "08H 00M 0S",
  ggplot_hr_var = TRUE,
  angle_x_axis = 25
)

hrt_rt_var

## End(Not run)

inner function of 'compute_elapsed_time'

Description

inner function of 'compute_elapsed_time'

Usage

inner_elapsed_time(secs, estimated = FALSE)

Arguments

Value

a character string showing the estimated or elapsed time

Create a Leafet map (including information pop-ups)

Description

Create a Leafet map (including information pop-ups)

Usage

leafGL_point_coords(
  dat_gps_tcx,
  color_points_column = "AltitudeMeters",
  provider = leaflet::providers$Esri.WorldImagery,
  option_viewer = rstudioapi::viewer,
  CRS = 4326
)

Arguments

Value

a leaflet map of class 'leaflet'

Examples

## Not run: 

require(fitbitViz)

# export the TCX file from the Fitbit website or app for the desired activity

res_tcx <- GPS_TCX_data(
  tcx_file = "/path/to/activity.tcx",
  time_zone = "Europe/Athens",
  verbose = TRUE
)
str(res_tcx)


# ........................
# then visualize the data
# ........................

res_lft <- leafGL_point_coords(
  dat_gps_tcx = res_tcx,
  color_points_column = "AltitudeMeters",
  provider = leaflet::providers$Esri.WorldImagery,
  option_viewer = rstudioapi::viewer,
  CRS = 4326
)
res_lft

## End(Not run)

This plot function is used in the 'fitbit_data_type_by_date' internally to plot the 'spo2' and 'hrv' data types

Description

This plot function is used in the 'fitbit_data_type_by_date' internally to plot the 'spo2' and 'hrv' data types

Usage

plot_data_type(dat_type_min, type)

Rayshader 3-dimensional using the Copernicus DEM elevation data

Description

Rayshader 3-dimensional using the Copernicus DEM elevation data

Usage

rayshader_3d_DEM(
  rst_buf,
  rst_ext,
  linestring_ASC_DESC = NULL,
  elevation_sample_points = NULL,
  zoom = 0.5,
  windowsize = c(1600, 1000),
  add_shadow_rescale_original = FALSE,
  verbose = FALSE
)

Arguments

Value

it doesn't return an object but it displays a 3-dimensional 'rayshader' object

References

https://www.tylermw.com/a-step-by-step-guide-to-making-3d-maps-with-satellite-imagery-in-r/

Examples

## Not run: 

require(fitbitViz)

# export the TCX file from the Fitbit website or app for the desired activity

res_tcx <- GPS_TCX_data(
  tcx_file = "/path/to/activity.tcx",
  time_zone = "Europe/Athens",
  verbose = TRUE
)
str(res_tcx)

# ....................................................
# then compute the sf-object buffer and raster-extend
# ....................................................

sf_rst_ext <- extend_AOI_buffer(
  dat_gps_tcx = res_tcx,
  buffer_in_meters = 1000,
  CRS = 4326,
  verbose = TRUE
)
sf_rst_ext

# ...............................................................
# Download the Copernicus DEM 30m elevation data because it has
# a better resolution, it takes a bit longer to download because
# the .tif file size is bigger
# ...............................................................

dem_dir <- tempdir()
# dem_dir

dem30 <- CopernicusDEM::aoi_geom_save_tif_matches(
  sf_or_file = sf_rst_ext$sfc_obj,
  dir_save_tifs = dem_dir,
  resolution = 30,
  crs_value = 4326,
  threads = parallel::detectCores(),
  verbose = TRUE
)

TIF <- list.files(dem_dir, pattern = ".tif", full.names = T)
# TIF

if (length(TIF) > 1) {
  # ....................................................
  # create a .VRT file if I have more than 1 .tif files
  # ....................................................

  file_out <- file.path(dem_dir, "VRT_mosaic_FILE.vrt")

  vrt_dem30 <- create_VRT_from_dir(
    dir_tifs = dem_dir,
    output_path_VRT = file_out,
    verbose = TRUE
  )
}

if (length(TIF) == 1) {
  # ..................................................
  # if I have a single .tif file keep the first index
  # ..................................................

  file_out <- TIF[1]
}

raysh_rst <- crop_DEM(
  tif_or_vrt_dem_file = file_out,
  sf_buffer_obj = sf_rst_ext$sfc_obj,
  verbose = TRUE
)

# terra::plot(raysh_rst)


# ................................................................
# create the 'elevation_sample_points' data.table parameter based
# on the min., middle  and max. altitude of the 'res_tcx' data
# ................................................................

idx_3m <- c(
  which.min(res_tcx$AltitudeMeters),
  as.integer(length(res_tcx$AltitudeMeters) / 2),
  which.max(res_tcx$AltitudeMeters)
)

cols_3m <- c("latitude", "longitude", "AltitudeMeters")
dat_3m <- res_tcx[idx_3m, ..cols_3m]
# dat_3m

# ...............................................................
# Split the route in 2 parts based on the maximum altitude value
# ...............................................................

linestring_dat <- gps_lat_lon_to_LINESTRING(
  dat_gps_tcx = res_tcx,
  CRS = 4326,
  time_split_asc_desc = NULL,
  verbose = TRUE
)

# .....................................................
# Conversion of the 'SpatRaster' to a raster object
# because the 'rayshader' package accepts only rasters
# .....................................................

rst_obj <- raster::raster(raysh_rst)
raster::projection(rst_obj) <- terra::crs(raysh_rst, proj = TRUE)


# .....................................
# open the 3-dimensional rayshader map
# .....................................

ray_out <- rayshader_3d_DEM(
  rst_buf = rst_obj,
  rst_ext = sf_rst_ext$raster_obj_extent,
  linestring_ASC_DESC = linestring_dat,
  elevation_sample_points = dat_3m,
  zoom = 0.5,
  windowsize = c(1600, 1000),
  add_shadow_rescale_original = FALSE,
  verbose = TRUE
)

## End(Not run)

sleep data heatmap

Description

sleep data heatmap

Usage

sleep_heatmap(level_data, angle_x_axis = 0)

Arguments

Value

a plot object of class ggplot2

Sleep Data of single day

Description

Sleep Data of single day

Usage

sleep_single_day(
  sleep_data,
  date = "2021-03-09",
  ggplot_color_palette = "ggsci::blue_material",
  verbose = FALSE
)

Arguments

Value

an object of class list

Examples

## Not run: 

require(fitbitViz)

# 'sleep_data_day' is the parsed JSON list for a single date from the Fitbit sleep endpoint

lst_out <- sleep_single_day(
  sleep_data = sleep_data_day,
  date = "2021-03-09",
  ggplot_color_palette = "ggsci::blue_material",
  verbose = TRUE
)
str(lst_out)

## End(Not run)

Sleep Data Time Series

Description

Sleep Data Time Series

Usage

sleep_time_series(
  sleep_data_list,
  ggplot_color_palette = "ggsci::blue_material",
  ggplot_ncol = NULL,
  ggplot_nrow = NULL,
  verbose = FALSE
)

Arguments

Value

an object of class list

Examples

## Not run: 

require(fitbitViz)

# 'sleep_data_list' is a named list (names = dates "YYYY-MM-DD")
# of parsed Fitbit sleep endpoint responses

sleep_ts <- sleep_time_series(
  sleep_data_list = sleep_data_list,
  ggplot_color_palette = "ggsci::blue_material",
  verbose = TRUE
)

sleep_ts$plt_lev_segments
sleep_ts$plt_lev_heatmap
sleep_ts$heatmap_data


# ...........................................
# (option to) save the ggplot to a .png file
# ...........................................

png_file <- tempfile(fileext = ".png")

ggplot2::ggsave(
  filename = png_file,
  plot = sleep_ts$plt_lev_segments,
  device = "png",
  scale = 1,
  width = 35,
  height = 25,
  limitsize = TRUE
)

## End(Not run)

function for the weeks (including the date-from and date-to)

Description

function for the weeks (including the date-from and date-to)

Usage

split_year_in_weeks(year)

Arguments

Value

a sequence of Dates of class 'Date'

References

https://statistics.berkeley.edu/computing/faqs/dates-and-times-r