---
title: "Standard workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Standard workflow of the eRTG3D}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
<style>
body {
text-align: justify}
</style>
```{r, echo = FALSE, eval=TRUE, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
options(knitr.table.format = "html", rmarkdown.html_vignette.check_title = FALSE)

library(eRTG3D)
set.seed(123)
```

This vignette illustrates the basic functionality of the `eRTG3D` package and some workflows, to combine the functions in a meaningful way. For a more detailed description of the individual functions and their parameters please consider the package's help.

## Workflow
### 1. Movement characteristics (P)
As first step the properties of a track with x, y and z coordinates are calculated.

```{r eval=FALSE}
niclas <- track.properties.3d(niclas)
```

```{r echo=FALSE, results = "asis", fig.height=5, fig.width=10}
niclas <- track.properties.3d(niclas)
pander::pandoc.table(head(round(niclas, 2),5))
```

Then the movement characteristics (P probability) are extracted from the trajectory. Although the algorithm also works without a DEM, the DEM should be passed to the `get.track.densities.3d()` function, otherwise the flight height distribution in respect to the earth surface can not be built, which ends in less accurate results.

```{r eval=FALSE}
P <- get.track.densities.3d(niclas, heightDistEllipsoid = TRUE, DEM = dem)
```

### 2. Attraction term (Q)
The finally desired Conditional Empirical Random Walk (CERW) connecting a given start with a certain end point by a given number of steps needs an attraction term (the Q probability) to ensure that the target is approached and hit.
In order to calculate the Q probability for each step the distribution of turns and lifts to target and the distribution of distance to target has to be known. They can be derived from the empirical data (ideally),
or estimated from an unconditional process with the same properties. In this case the Q probabilities, which represent the pull towards the destination, are extracted from a UERW simulated with `sim.uncond.3d()`. The UERW should contain 1500 `f <- 1500` times more steps than the final CERW to be simulated. Q are extracted from the UERW by the function `qProb.3d()`.

```{r eval=FALSE}
sim.locs <- nrow(niclas)
f <- 1500
uerw <- sim.uncond.3d(sim.locs*f, start = c(niclas$x[1], niclas$y[1], niclas$z[1]), 
                      a0 = niclas$a[1], g0 = niclas$g[1], densities = P)
Q <- qProb.3d(uerw, sim.locs)
```

### 3. Boundary conditions
Set up the start and end conditions: azimuth (`a0`), gradient (`g0`), start and end point of the CERW to be simulated.

```{r eval=FALSE}
start <- c(niclas$x[1], niclas$y[1], niclas$z[1])
end <- c(niclas$x[nrow(niclas)], niclas$y[nrow(niclas)], niclas$z[nrow(niclas)])
a0 <- niclas$a[1]
g0 <- niclas$g[1]
```

### 4. Conditional Empirical Random Walk
Then finally a CERW can be simulated.

```{r eval=FALSE}
cerw <- sim.cond.3d(sim.locs, start = start, end = end, a0 = a0, g0 = g0,
                    densities = P, qProbs = Q, DEM = dem)
```

If more than one simulated track is desired, the `n.sim.cond.3d()` can be used. The n.sim parameter defines the number of simulated tracks.

```{r eval=FALSE}
cerwList <- n.sim.cond.3d(n.sim = 100, sim.locs,
                          start = start, end = end, a0 = a0, g0 = g0,
                          densities = P, qProbs = Q, DEM = dem)
```

**Note:** Due to dead ends, which are normally occurring in a proportion of 25%, the n.sim parameter should be set higher than the needed tracks.

## Extract densities from multiple track sections
In many cases the time between the acquisition of fix points of the GPS tracks is not constant.
This can be caused by the time to get the fix point or missing data. To avoid distorted statistic distributions,
which increases the probability of dead ends, the track has to be splitted in sections, where the acquisition time is constant. In this case the `get.track.properties.3d()` function can not be used anymore. Then the work flow should look like the following:

```{r eval=FALSE}
trackSections <- track.split.3d(track, timeLag)
P <- get.section.densities.3d(trackSections, DEM = dem)
```

**Note:** If the aim is to reproduce a track, then the length of the track should be adjusted to fit to the densities extracted by `get.section.densities.3d()`. The message thrown by the previously applied `track.split.3d()` proposes a value `nChange` to adjust the track length of the simulations.

## Wrapper function to reproduce tracks
To reproduce an observed track, it is the simplest to just apply the `reproduce.track.3d()` function on the track and the DEM. The function automatically wraps all steps above together. To produce multiple tracks, the `n.sim` variable can be used.

```{r, fig.show='hold', eval=FALSE}
cerwList <- reproduce.track.3d(n.sim = 100, niclas, DEM = dem)
```