README.Rmd

---
output: github_document
bibliography: bibliography.bib
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

# stopdetection

<!-- badges: start -->
<!-- badges: end -->

This package implements the stop detection algorithm as outlined in @Ye2009-dv. This package provides a set of tools to cluster timestamped movement trajectories into sets of stops (or stay points) and tracks (or trajectories). Time-adjacent clusters are formed by first identifying stops on the basis of provided dwell time and radius parameters. A stop is created if all subsequent locations are within a certain distance of an initiating location for at least as long as the dwell time. For example, 200 meters and 5 minutes may be used in order to find all clusters within the trajectory for which a person remained within a circle with radius 200 meters for at least five minutes.

It is recommended to merge stops following the initial stop identification, as documented in @Montoliu2013-tb. Merging stops requires a parameter for the maximum distance away from each other that two stops may be while being considered the same stop. Single points between two stops adjacent in time are removed during this step. In data where locations are measured without error, this step is optional. Where locations are generated with error, this step provides an error correcting mechanism for erroneous and low-accuracy locations.

## Installation

You can install the development version of stopdetection from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("daniellemccool/stopdetection")
```

## Example

The following demonstrates the stopFinder algorithm with a distance radius parameter of 200 meters, and a minimum time parameter of 200 seconds.


```{r example}
library(data.table)
library(stopdetection)
data("loc_data_2019")
setDT(loc_data_2019)
stopFinder(loc_data_2019, thetaD = 200, thetaT = 200)
```
## Extract states

Use \code{returnStateEvents} to quickly extract a data.table containing information about the stops and tracks

```{r example2}
returnStateEvents(loc_data_2019)
```

## Merge stops/handle short tracks

Subsequent nearby stops can be merged based on the distance of their centroids. This is often useful if they represent the same stop subjectively. Short tracks can be either merged into the previous stop or excluded. Often short 'tracks' represent erroneously measured GNSS locations of one or two points, so excluding them is helpful. The combination of excluding short tracks and merging stops can be used to handle noisy location data. 

```{r example3}
mergingCycle(loc_data_2019, thetaD = 200, small_track_action = "exclude", max_locs = Inf, max_dist = 200)
returnStateEvents(loc_data_2019)
```

# References