---
title: "ActFrag"
author: "Junrui Di"
date: "6/24/2018"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Activity Fragmentation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
This is the vignette for `ActFrag`. This package extracts commonly used fragmention features from minute level actigraphy data. Recent studies haven shown that, on top of total daily active/sedentary volumes, the time accumulation strategies provide more sensitive information. This package provides functions to extract commonly used fragmentation metrics to quantidy such time accumulation strategies based on minute level actigraphy-measured activity counts data.

To download the package from Github
```{r, eval=FALSE}
devtools::install_github("junruidi/ActFrag")
```

And to load in the package into the R environment
```{r}
library(ActFrag)
```


## 1. Data

The expected data should consider at least one data frame of minute level activity counts, stored in a format of `data.frame` of dimension $(\sum_i d_i) \times 1442$, where $d_i$ is the number of available days for subject i.And the order of the 1442 columns (and corresponding column names) should be "ID","Day","MIN1",..."MIN1440".

It is preferrable that user can also provide a `data.frame` of wear/non-wear flag as same dimension of the activity counts. This flag data can serve as the following purposes:

 1. Define time regions where the subjects were wearing the devices. E.g. in NHANES 2003 - 2006, protocol required subjects to remove the devices when sleep. Certian non-wear detection algorithms can be used  (see package [`rnahnesdata`](https://github.com/andrew-leroux/rnhanesdata) ).
 2. Separate sleep and wake period to derive domain specific features. E.g. when actigraphy record is paired with a sleep log, or when the device has built in sleep detecting algorithms. 
 3. Define regions where features should be calcualted. E.g, we want features to be calculated only for 5:00AM to 11:00PM.
 
 Thbe wear/nonwear flag data should only consist of entries 0/1 representing nonwear/wear, sleep/wake, regions of interest/regions of interests, respectively. This is especially crucial for calculating features like total sedentary time, fragmentation etc. Because, we are not supposed to mix sedentary with sleep. 
 
 If no wear/nonwear flag data is supplied, users can create one using the `wear_flag` function providing the time region:

```{r, eval=FALSE}
data(example_activity_data)
count = example_activity_data$count
weartime = wear_flag(count.data = count, start = "06:00", end = "23:00")
```

In this version, we only incorporate type 3 . For 1 and 2 there are more appropriate softwares to look for.



## 2. Fragmentation metrics

Frequently, studies extract total time spent in sedentary behavior (e.g., total sedentary minutes per day) or proportion of waking hours spent sedentary. More advanced techniques have examined the effect of replacing sedentary time with active time spent either in light or moderate-vigorous intensity. For example, isotemporal substitution modeling) and compositional data analysis examine the combined effects of time spent sedentary, light and moderate-vigorous activity, and sleep while taking into account the codependence due to finite time during a day. Yet, most studies typically only use total volume of sedentary time while ignoring the potential importance of accumulation patterns. Recent studies have suggested that such patterns (known as prolonged sedentary bouts) may provide additional sensitivity to predict health outcomes and provide additional information beyond total volume of sedentary time. 

Fragmentation metrics study the accumulation pattern of TST and TAT by quantifying the alternating these sequences via summaries of duration of and fre- quency of switching between sedentary and active bouts. They provide unique translatable insights into accumulation patterns for sedentary and active time and lead to additional findings of associations between those patterns and health outcomes on top of total sedentary volume Here is the list of available fragmentation metrics:

* average bout duration: bout/minute
* transition probability: reexpressed as the reciprocal of averge bout durations
* Gini index: absolute variability normalized to the average bout duration
* average hazard
* power law distribution parameter

We can calculate the above mentioned metrics for both sedentary and active bout. Details about fragmentations can be found [here](https://www.biorxiv.org/content/early/2017/08/31/182337).

`fragmentation` and `fragmentation_long` calcualte fragmentation features, (for a single vector amd whole dataset respectively). The argument `metrics`, which consists of "mean_bout", "TP", "Gini", "hazard", "power", and "all" decides which metrics to calcualte. "all" will lead to all metrics.

For a single day of count (a vector):
```{r,eval=FALSE}
data(example_activity_data)
count1 = c(t(example_activity_data$count[1,-c(1,2)]))
wear1 = c(t(example_activity_data$wear[1,-c(1,2)]))
mb = fragmentation(x = count1, w = wear1, thresh = 100, metrics = "mean_bout",bout.length = 1)
tp = fragmentation(x = count1, w = wear1, thresh = 100, metrics = "TP",bout.length = 1)
```

Given all the activity and wear/nonwear flag data for the whole dataset, user can choose to calcualte framentation at daily level, or aggregate bouts across all available days by choosing from either "subject" and "day" for the argument `by`:
```{r,eval=FALSE}
data(example_activity_data)
count = example_activity_data$count
wear = example_activity_data$wear
frag_by_subject = fragmentation_long(count.data = count, weartime = wear,thresh = 100, metrics = "all",by = "subject",bout.length = 1)
frag_by_day = fragmentation_long(count.data = count, weartime = wear,thresh = 100, metrics = "all",by = "day",bout.length = 1)
```

