skipTrack

skipTrack: An R package for Identifying Skips in Self-Tracked Mobile Menstrual Cycle Data - Published in JOSS (2024)

https://github.com/lukeduttweiler/skiptrack

Repository

Bayesian Hierarchical Models for Identifying Non-Adherence in Mobile Menstrual Cycle Tracking

README.Rmd

---
output: github_document
bibliography: 'bibliography.bib'
header-includes: 
  - \usepackage{amsmath}
  - \usepackage{xcolor}
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# skipTrack


[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![R-CMD-check](https://github.com/LukeDuttweiler/skipTrack/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/LukeDuttweiler/skipTrack/actions/workflows/R-CMD-check.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/skipTrack)](https://CRAN.R-project.org/package=skipTrack)


Welcome to the SkipTrack Package! 

SkipTrack is a Bayesian hierarchical model for self-reported menstrual cycle length data on mobile health apps. The model is an extension of the hierarchical model presented in @li2022predictive that focuses on predicting an individual's next menstrual cycle start date while accounting for cycle length inaccuracies introduced by non-adherence in user self-tracked data. Check out the 'Getting Started' vignette to see an overview of the SkipTrack Model!

## Installation

``` r
#Install from CRAN
install.packages('skipTrack')

#Install Development Version
devtools::install_github("LukeDuttweiler/skipTrack")
```

# Package Usage

The SkipTrack package provides functions for fitting the SkipTrack model, evaluating model run diagnostics, retrieving and visualizing model results, and simulating related data. We begin our tutorial by examining some simulated data. 

```{r}
library(skipTrack)
```

First, we simulate data on 100 individuals from the SkipTrack model where each observed $y_{ij}$ value has a 75% probability of being a true cycle, a 20% probability of being two true cycles recorded as one, and a 5% probability of being three true cycles recorded as one. 

```{r}
set.seed(1)

#Simulate data
dat <- skipTrack.simulate(n = 100, model = 'skipTrack', skipProb = c(.75, .2, .05))
```

Fitting the SkipTrack model using this simulated data requires a call to the function `skipTrack.fit`. Note that because this is a Bayesian model and is fit with an MCMC algorithm, it can take some time with large datasets and a high number of MCMC reps and chains. 

In this code we ask for 4 chains, each with 1000 iterations, run sequentially. Note that we recommend allowing the sampler to run longer than this (usually at least 5000 iterations per chain), but we use a short run here to save time.

If `useParallel = TRUE`, the MCMC chains will be evaluated in parallel, which helps with longer runs.

```{r}
ft <- skipTrack.fit(Y = dat$Y, cluster = dat$cluster,
                    reps = 1000, chains = 4, useParallel = FALSE)
```

Once we have the model results we are able to examine model diagnostics, visualize results from the model, and view a model summary. 

### Diagnostics

Multivariate, multichain MCMC diagnostics, including traceplots, Gelman-Rubin diagnostics, and effective sample size, are all available for various parameters from the model fit. These are supplied using the `genMCMCDiag` package, see that packages' documentation for details.

Here we show the output of the diagnostics on the $c_{ij}$ parameters, which show that (at least for the $c_{ij}$ values) the algorithm is mixing effectively (or will be, once the algorithm runs a little longer).

```{r, fig.align='center', fig.width = 7, fig.height=7}
skipTrack.diagnostics(ft, param = 'cijs')
```

### Visualization

In order to see some important plots for the SkipTrack model fit, you can simply use `plot(ft)`, and the plots are directly accessible using `skipTrack.visualize(ft)`.

```{r, fig.align='center', fig.width = 7, fig.height=7}
plot(ft)
```

### Summary

A summary is available for the SkipTrack model fit with `summary(ft)`, with more detailed results accessible through `skipTrack.results(ft)`. Importantly, these results are based on a default chain burn-in value of 750 draws. This can be changed using the parameter `burnIn` for either function.

For example using `summary` with the default burnIn...
```{r, eval=FALSE}
summary(ft)
```

produces the following output:

```{r, echo = FALSE}
summary(ft)
```

On the other hand if we change the burnIn to 500...

```{r, eval = FALSE}
summary(ft, burnIn = 500)
```

we see:

```{r, echo = FALSE}
summary(ft, burnIn = 500)
```

This introduction provides enough information to start fitting the SkipTrack model. For further information regarding different methods of simulating data, additional model fitting, and tuning parameters for fitting the model, please see the help pages and the 'Getting Started' vignette. Additional vignettes are forthcoming.

\newpage

## Bibliography

Owner

JOSS Publication

skipTrack: An R package for Identifying Skips in Self-Tracked Mobile Menstrual Cycle Data

Published

September 16, 2024

DOI

10.21105/joss.06928

Volume 9, Issue 101, Page 6928

Authors

Luke Duttweiler
Department of Biostatistics, Harvard T.H. Chan School of Public Health, Boston, MA, United States

Shruthi Mahalingaiah
Department of Epidemiology, Harvard T.H. Chan School of Public Health, Boston, MA, United States

Brent Coull
Department of Biostatistics, Harvard T.H. Chan School of Public Health, Boston, MA, United States

Editor

Sehrish Kanwal

Tags

menstrual cycle Bayesian hierarchical model MCMC

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages