---
title: "activityCounts"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{activityCounts}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = T, echo= FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

#### Calculate ActiLife counts from raw acceleration data

<style>
  body{
    line-height: 1.8em;
  }
</style>
  
# Introduction
Many research areas use accelerometers to study people's activities including sleep, sedentary behaviour, and physical activity. Actigraph is one of the most common research grade accelerometers. Actigraph accelerometers include ActiLife is a closed-source software, which generates [activity counts](https://s3.amazonaws.com/actigraphcorp.com/wp-content/uploads/2017/11/26205758/ActiGraph-White-Paper_What-is-a-Count_.pdf). There is considerable research validating and developing algorithms for human activity using Actilife counts. Unfortunately, Actilife counts are proprietary and difficult to implement if researchers use different accelerometer brands. Recently, [Brond et al.](https://pubmed.ncbi.nlm.nih.gov/28604558/) developed a [code](https://github.com/jbrond/ActigraphCounts) in MATLAB, which can convert raw accelerometer data to Actilife counts. Their work can help researchers use different accelerometers and calculate Actilife counts, MATLAB is a commercial program. Unlike MATLAB, R is open-source, and also R is very popular among health and activity researchers. The package activityCounts allow users to convert the accelerometer data to Actilife counts.

<br>

# How to use
## Install R
Visit [R Project](https://www.r-project.org/) to download and install R.

## Install POSIT (recommended)
Although it is not necessary, RStudio Desktop makes using R easier. To install the latest version, go to [POSIT](https://posit.co/products/open-source/rstudio/) and download the installation file based on your operating system.

## Install activityCounts

You can install the released version of activityCounts from [CRAN](https://CRAN.R-project.org) with running the following code in the R console:

``` {r , eval = FALSE}
install.packages("activityCounts")
```

And the development version from [GitHub](https://github.com/walkabillylab/activityCounts) with:

``` {r eval=FALSE}
install.packages("devtools")
devtools::install_github("walkabillylab/activityCounts")
```

## Load activityCounts
To load the package and its sample datasets run the following in R console:


```{r setup}
library(activityCounts)
```


## Import your data
To generate the counts, import your data from your source file. Store the data inside a variable so you can pass that the main function of the package, `counts()`. 
For example, you can use the `read_csv()` function from the `tidyverse` package to import your data:
Note that the dataset must have three columns which X, Y, and Z readings.

```{r eval=FALSE}
# install.packages("tidyverse")
raw_accel_data <- tidyverse::read_csv("~/your_raw_accelerometer_data.csv")
```


## Use the counts() function
To generate the counts, provide the function `counts()` with your data and the sampling frequency of the data.
```{r eval=FALSE}
# assume sampling frequency is 100 Hz
sampling_frequency <- 100 
counts_measures <- activityCounts::counts(data = raw_accel_data, hertz = sampling_frequency)
```

Now the variable `counts_measures` contains three columns which indicate the calculated counts for X, Y, and Z axes respectively. If the data frequency is less than 30 Hz, first resample your data and increase the frequency to more than 30 Hz and then calculate the counts.



# Example
## Check the sample input dataset:
activityCounts package includes a sample dataset which is available for testing by importing the package. The name of the dataset is `sampleXYZ` and its sampling frequency is 100Hz. To check out sampleXYZ:

```{r}
data("sampleXYZ")
head(sampleXYZ)
```

## How to calculates counts:
For sampleXYZ data, the first column is X, second is Y, and the third column is the Z axis, therefore when calling the function, specify the columns in the argument section. Now by applying the function `counts()` calculate the counts for sampleXYZ.

```{r eval=FALSE}
sampleXYZ_counts <- counts(data = sampleXYZ, hertz = 100 ,x_axis = 1,y_axis = 2,z_axis = 3)
head(sampleXYZ_counts)
```

### Use your own data:

By default, the second column of your dataset should contain accelerometer data for x-axis, the third column for y-axis and the forth column for the z-axis However, you can specifically tell the counts() function which columns have the x, y, and z-axis data. Use x_axis, y_axis, and z_axis arguments when calling the function to specify the desired columns for each axes.

In this example code, the first column has the time stamp for the data. The second column has the x-axis data, the third column has the y-axis data, and the fourth column has the z-axis data. Therefore, assuming the sampling frequency is 100 Hz, we call the function like this:

```{r eval=FALSE}
calculated_output <- counts(data = your_raw_data, hertz = 100, x_axis = 2, y_axis = 3, z_axis = 4)
```
The default values for x_axis, y_axis, and z_axis are one, two, and three respectively. So if you don't specify them, the function assumes the first column is for the x-axis, the second for the y-axis and the third is for the z-axis.


## Compare the sample outputs:

The other dataset that comes with this package has nine columns; the first three columns are the raw accelerometer data from sampleXYZ, the next three columns are the counts calculated by the counts() function for X, Y, and Z axes. Finally, the last three columns are counts calculated by the ActiLife software. To check the data run the following:


```{r message=FALSE, warning=FALSE}
summary(sampleCounts)
```

## Visualize the difference:

As the summary shows, the counts calculated by activityCounts package and the software ActiLife are very close. In these plots, counts calculated by the package are sketched versus the counts calculated by the ActiLife software. The straight lines show strong correlations: 
  
```{r echo=FALSE, message=FALSE, warning=FALSE}
plot(sampleCounts$activityCounts_x_counts, sampleCounts$ActiLife_x_counts)
plot(sampleCounts$activityCounts_y_counts, sampleCounts$ActiLife_y_counts)
plot(sampleCounts$activityCounts_z_counts, sampleCounts$ActiLife_z_counts)
```
