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.

niclas <- track.properties.3d(niclas)
x y z a g t l d
2556476 1188336 1284 0.39 1.56 NA NA NA
2558565 1189297 1360 0.43 1.54 0.04 -0.02 2301
2560477 1189861 1370 0.29 1.57 -0.14 0.03 1993
2562431 1190668 1392 0.39 1.56 0.11 -0.01 2114
2563809 1190657 1807 -0.01 1.28 -0.4 -0.28 1439

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.

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().

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.

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.

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.

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:

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.

cerwList <- reproduce.track.3d(n.sim = 100, niclas, DEM = dem)