---
title: "Getting started with `amt`"
author: "Johannes Signer"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with amt}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Basics

### Creating a track

The basic building blocks of `amt` are tracks. Tracks are `data_frame`s with at least two columns that contain the coordinates: `x_` and `y_`. A track behaves exactly like a `data_frame` (the only difference being that we added an other S3 class).

```{r, warning=FALSE, message=FALSE}
library(amt)
df1 <- data_frame(x = 1:3, y = 1:3)
is.data.frame(df1)
df1

# Now we can create a track
tr1 <- mk_track(df1, x, y)
is.data.frame(tr1)
tr1

```

At the moment there are two types of tracks:

- `track_xy` is a track that only has coordinates, and
- `track_xyt` is a track that has a timestamp associated to each coordinate pair.

Whether a `track_xy` or `track_xyt` is created is determined whether or not a timestamp is passed to the function `mk_track`. In the previous example we only passed `x` and `y` coordinates. Hence a `track_xy` was created.


```{r}
class(tr1)
```

To create a `track_xyt` we could do the following

```{r}
df1 <- data_frame(x = 1:3, y = 1:3, t = lubridate::ymd("2017-01-01") + lubridate::days(0:2))
tr2 <- mk_track(df1, x, y, t)
class(tr2)
```

From the output above we see that a `track_xyt` is also a `track_xy`. This means that all methods for `track_xy` also work for a `track_xyt` (but not the reverse).


### Adding additional information

We can also add additional information for each relocation (e.g., the id of the animal, or some other sensor information such as the DOP). Any number of additional named columns can be passed to `mk_track`. By named we mean, that columns should always be passed in the form of `col_name = content` to avoid confusion with coordinates and time stamp. We will extend the dummy example from above, by passing 2 more columns (the id of animal and the age).

```{r}
df1 <- data_frame(x = 1:3, y = 1:3, t = lubridate::ymd("2017-01-01") + lubridate::days(0:2), 
                  id = 1, age = 4)

# first we only create a track_xy
tr3 <- mk_track(df1, x, y, id = id, age = age)
tr3

# now lets create a track_xyt
tr4 <- mk_track(df1, x, y, t, id = id, age = age)
tr4
```

### Coordinate refenece system

`mk_track` has one further optional argument (`crs`), which allows the user to set a coordinate reference system (CRS) of the track. The CRS needs to be provided as valid `proj4string`, see the documentation of `sp::CRS` for further details. 

### An example with real data

In the `amt` relocation data of one red deer from northern Germany is included. We will use this data set to to illustrate how to create a track.

We benign with loading and inspecting the data.

```{r}
data(sh)
head(sh)
```

Before creating a track, we have to do some data cleaning:

1. check if any coordinates are missing (and if so, remove the relocation), 
2. parse the date and time, 
3. create a time stamp, 
4. check for duplicated time stamps, and
5. create two new columns for the id and month of the year.

```{r}
# check if all observations are complete
all(complete.cases(sh)) # no action required

# parse date and time and create time stamps
sh$ts <- as.POSIXct(lubridate::ymd(sh$day) +
                      lubridate::hms(sh$time))

# check for duplicated time stamps
any(duplicated(sh$ts))

# We have some duplicated time stamps, these need to be removed prior to
# creating a track.
sh <- sh[!duplicated(sh$ts), ]

# create new columns
sh$id <- "Animal 1"
sh$month <- lubridate::month(sh$ts)
```

Now we can create a track.

```{r}
tr1 <- mk_track(sh, x_epsg31467, y_epsg31467, ts, id = id, month = month)
```

The column names of the data set already indicate the CRS of the data. We can add this information when creating a track.

```{r}
tr1 <- mk_track(sh, x_epsg31467, y_epsg31467, ts, id = id, month = month, 
                crs = sp::CRS("+init=epsg:31467"))
```

### A note on pipes (`%>%`)
`amt` was heavily inspired through workflows suggested by the popular packages from the `tidyverse`. The above steps could easily be connected using pipes. Note that result will be exactly the same.

```{r}
data(sh)
tr2 <- sh %>% filter(complete.cases(.)) %>% 
  mutate(
    ts = as.POSIXct(lubridate::ymd(day) + lubridate::hms(time)), 
    id = "Animal 1", 
    month = lubridate::month(ts)
  ) %>% 
  filter(!duplicated(ts)) %>% 
  mk_track(x_epsg31467, y_epsg31467, ts, id = id, month = month, 
           crs = sp::CRS("+init=epsg:31467"))
tr2
```

## Working with tracks

### Utility functions
#### Basic manipulation

Remember, that `tracks_xy*` behave like regular `data.frames`. This means that we can use all data manipulation verbs that we are used from `base` R or `tidyverse`. For example we an filter a track based on some characteristic. As an example we extract all relocations from May.

```{r}
tr3 <- tr2 %>% filter(month == 5)

# we are left with a track
class(tr3)
```


#### Transforming CRS

If we set the CRS when creating a track (we can verify this with `has_crs`), we can transform the CRS of the coordinates with the function `transform_coords` (a wrapper around `sp::spTransform`). For illustration we will transform the CRS of `tr2` to geographical coordinates (EPSG:4326).

```{r}
transform_coords(tr2, sp::CRS("+init=epsg:4326"))
```

### Some initial data exploration

Several functions for calculating derived quantities are available. We will start with looking at step length. The function `step_lengths` can be used for this.

```{r}
tr2 <- tr2 %>% mutate(sl_ = step_lengths(.))
```

If we look at a summary of `sl_`

```{r}
summary(tr2$sl_)
```

Note, 1) there is one `NA` for step lengths, this is expected, because we are still in a point representation (i.e., there is no step length for the last relocation). 2) the range is quiet large from 0 to almost 5km. Before looking at step lengths in any further detail, we will have to make sure the sampling rate is more or less regular.

The function `summarize_sampling_rate` provides an easy way to look at the sampling rate.

```{r}
summarize_sampling_rate(tr2)
```


### From tracks to steps

todo



## How to deal with several animals

todo

## Session
```{r}
sessionInfo()
```

