Package 'eRTG3D'

Description

Calculates the chi maps for one rasterStack or all raster all the raster pairs stored in two rasterStacks. As observed values, the first stack is used. The expected value is either set to the mean of the first stack, or if given to be the values of the second stack.

Usage

chiMaps(stack1, stack2 = NULL, verbose = FALSE)

Arguments

Value

A rasterStack containing the chi maps.

Examples

print("tbd.")

Description

This is data to be included in the package and can be used to test its functionality. The dem data is a RasterLayer and has a resolution of 90 meters. It is the topography of the Swiss midlands. The complete dataset can be downloaded directly from http://srtm.csi.cgiar.org/srtmdata/.

References

https://srtm.csi.cgiar.org/srtmdata/

Description

Crops the DEM to the extent of the track with a buffer

Usage

dem2track.extent(DEM, track, buffer = 100)

Arguments

Value

A the cropped digital elevation model as a raster layer.

Examples

dem2track.extent(dem, niclas)

Description

Distance of each track point to a given point

Usage

dist2point.3d(track, point, groundDistance = FALSE)

Arguments

Value

Returns the distance of each track point to the point.

Examples

dist2point.3d(niclas, c(0, 0, 0))

Description

Calculates the distance between every point in the track and the last point (target).

Usage

dist2target.3d(track)

Arguments

Value

A numeric vector with the distances to target

Examples

dist2target.3d(niclas)

Description

The empirically informed random trajectory generator in three dimensions (eRTG3D) is an algorithm to generate realistic random trajectories in a 3-D space between two given fix points in space, so-called Conditional Empirical Random Walks. The trajectory generation is based on empirical distribution functions extracted from observed trajectories (training data) and thus reflects the geometrical movement characteristics of the mover. A digital elevation model (DEM), representing the Earth's surface, and a background layer of probabilities (e.g. food sources, uplift potential, waterbodies, etc.) can be used to influence the trajectories.

Details

See the packages site on GitHub, detailed information about the algorithm in this Master’s Thesis, or test the algorithm online in the eRTG3D Simulator.

Description

Function to filter out tracks that have found a dead end

Usage

filter.dead.ends(cerwList)

Arguments

Value

A list that is only containing valid tracks.

Examples

filter.dead.ends(list(niclas, niclas))

Description

Creates a list consisting of the three dimensional probability distribution cube for turning angle, lift angle and step length (turnLiftStepHist) as well as the uni-dimensional distributions of the differences of the turn angles, lift angles and step lengths with a lag of 1 to maintain minimal level of autocorrelation in each of the terms. Additionally also the distribution of the flight height over the ellipsoid (absolute) and the distribution of flight height over the topography (relative) can be included.

Usage

get.densities.3d(
  turnAngle,
  liftAngle,
  stepLength,
  deltaLift,
  deltaTurn,
  deltaStep,
  gradientAngle = NULL,
  heightEllipsoid = NULL,
  heightTopo = NULL,
  maxBin = 25
)

Arguments

Value

A list containing the tldCube and the autodifferences functions (and additionally the flight height distribution functions)

Examples

niclas <- track.properties.3d(niclas)[2:nrow(niclas), ]
P <- get.densities.3d(
  turnAngle = niclas$t, liftAngle = niclas$l, stepLength = niclas$d,
  deltaLift = diff(niclas$t), deltaTurn = diff(niclas$l), deltaStep = diff(niclas$d),
  gradientAngle = NULL, heightEllipsoid = NULL, heightTopo = NULL, maxBin = 25
)

Description

Calculates the ratio between horizontal movement and vertical movement. The value expresses the distance covered forward movement per distance movement in sinking.

Usage

get.glideRatio.3d(track)

Arguments

Value

The ratio between horizontal and vertical movement.

Examples

get.glideRatio.3d(niclas)

Description

Creates a list consisting of the 3 dimensional probability distribution cube for turning angle, lift angle and step length (turnLiftStepHist) as well as the uni-dimensional distributions of the differences of the turning angles, lift angles and step lengths with a lag of 1 to maintain minimal level of autocorrelation in each of the terms.

Usage

get.section.densities.3d(
  trackSections,
  gradientDensity = TRUE,
  heightDistEllipsoid = TRUE,
  DEM = NULL,
  maxBin = 25
)

Arguments

Value

A list containing the tldCube and the autodifferences functions (and additionally the height distribution function)

Examples

get.section.densities.3d(list(niclas[1:10, ], niclas[11:nrow(niclas), ]))

Description

Get densities creates a list consisting of the 3 dimensional probability distribution cube for turning angle, lift angle and step length (turnLiftStepHist) as well as the uni-dimensional distributions of the differences of the turning angles, lift angles and step lengths with a lag of 1 to maintain minimal level of autocorrelation in each of the terms.

Usage

get.track.densities.3d(
  track,
  gradientDensity = TRUE,
  heightDistEllipsoid = TRUE,
  DEM = NULL,
  maxBin = 25
)

Arguments

Value

A list containing the tldCube and the autodifferences functions (and additionally the height distribution function)

Note

The time between the acquisition of fix points of the track must be constant, otherwise this leads to distorted statistic distributions, which increases the probability of dead ends. In this case please check track.split.3d and get.section.densities.3d

Examples

get.track.densities.3d(niclas, heightDist = TRUE)

Description

Tests if the object is a simple feature collection (class: 'sf, data.frame')

Usage

is.sf.3d(track)

Arguments

Value

A logical: TRUE if is a simple feature collection (class: 'sf, data.frame') of the sf package, FALSE otherwise.

Examples

is.sf.3d(niclas)
is.sf.3d(track2sf.3d(track = niclas, CRS = 2056))

Description

Calculates the lift angle between every point in the track and the last point (target).

Usage

lift2target.3d(track)

Arguments

Value

A numeric vector with the lift angles to target

Examples

lift2target.3d(niclas)

Description

Avoids the problem of -Inf occuring for log(0).

Usage

logRasterStack(rStack, standartize = FALSE, InfVal = NA)

Arguments

Value

A rasterStack in logarithmic scale

Examples

logRasterStack(raster::stack(dem))

Description

Applies a twosided moving median window on a vector, where the window paramter is the total size of the window. The value in the window middle is the index where the median of the window is written. Therefore the window size has to be an uneven number. The border region of the vetor is filled with a one-sided median. There might be border effects.

Usage

movingMedian(data, window)

Arguments

Value

A numeric vector.

Examples

movingMedian(sequence(1:10), window = 5)

Description

Creates multiple conditional empirical random walks, with a specific starting and ending point, geometrically similar to the initial trajectory by applying sim.cond.3d multiple times.

Usage

n.sim.cond.3d(
  n.sim,
  n.locs,
  start = c(0, 0, 0),
  end = start,
  a0,
  g0,
  densities,
  qProbs,
  error = FALSE,
  parallel = FALSE,
  DEM = NULL,
  BG = NULL
)

Arguments

Value

A list containing the CERWs or NULLs if dead ends have been encountered.

Examples

niclas <- track.properties.3d(niclas)
n.locs <- 3
P <- get.track.densities.3d(niclas)
f <- 1500
start <- Reduce(c, niclas[1, 1:3])
end <- Reduce(c, niclas[n.locs, 1:3])
a0 <- niclas$a[1]
g0 <- niclas$g[1]
uerw <- sim.uncond.3d(
  n.locs * f, start = start, a0 = a0, g0 = g0, densities = P
)
Q <- qProb.3d(uerw, n.locs)
n.sim.cond.3d(
  n.sim = 2, n.locs = n.locs,
  start = start, end = end,
  a0 = a0, g0 = g0,
  densities = P, qProbs = Q
)

Description

Creates conditional empirical random walks in gliding mode, between a start and end point. The walk is performed on a MODE layer and, if provided, additionally on a background and digital elevation layer. The gliding is simulated with sim.cond.3d and soaring with sim.uncond.3d, therefore soaring is not restricted towards the target and can happen completly free as long as there are good thermal conditions. It is important to extract for every mode in the MODE raster layer a corresponding densities object with get.densities.3d and pass them to the function.

Usage

n.sim.glidingSoaring.3d(
  n.sim = 1,
  parallel = FALSE,
  MODE,
  dGliding,
  dSoaring,
  qGliding,
  start = c(0, 0, 0),
  end = start,
  a0,
  g0,
  error = TRUE,
  smoothTransition = TRUE,
  glideRatio = 20,
  DEM = NULL,
  BG = NULL,
  verbose = FALSE
)

Arguments

Value

A list containing 'soaring-gliding' trajectories or NULLs if dead ends have been encountered.

Note

The MODE raster layer must be in the following structure: Gliding pixels have the value 1 and soaring pixel the values 2. NA's are not allowed in the raster.

Examples

print("tbd.")

Description

This is data to be included in the package and can be used to test its functionality. The track consists of x, y and z coordinates and represents the movement of a stork called niclas in the Swiss midlands.

References

https://www.movebank.org

Description

Function detects the operating system and chooses the approximate kind of process for parallelizing the task: Windows: PSOCKCluster, Unix: Forking.

Usage

parpbapply(
  X,
  FUN,
  MARGIN,
  packages = NULL,
  export = NULL,
  envir = environment(),
  nNodes = parallel::detectCores() - 1
)

Arguments

Value

Returns a vector or array or list of values obtained by applying a function to margins of an array or matrix.

Examples

n <- 1000
df <- data.frame(
  x = seq(1, n, 1),
  y = -seq(1, n, 1)
)
a <- parpbapply(X = df, FUN = sum, MARGIN = 1, nNodes = 2)

Description

Function detects the operating system and chooses the approximate kind of process for parallelizing the task: Windows: PSOCKCluster, Unix: Forking.

Usage

parpblapply(
  X,
  FUN,
  packages = NULL,
  export = NULL,
  envir = environment(),
  nNodes = parallel::detectCores() - 1
)

Arguments

Value

A list with the results.

Examples

square <- function(x) {
  x * x
}
l <- parpblapply(X = 1:1000, FUN = square, export = c("square"), nNodes = 2)

Description

Function detects the operating system and chooses the approximate kind of process for parallelizing the task: Windows: PSOCKCluster, Unix: Forking.

Usage

parpbsapply(
  X,
  FUN,
  packages = NULL,
  export = NULL,
  envir = environment(),
  nNodes = parallel::detectCores() - 1
)

Arguments

Value

A vector with the results.

Examples

square <- function(x) {
  x * x
}
s <- parpbsapply(X = 1:1000, FUN = square, export = c("square"), nNodes = 2)

Description

Plot function to plot the 3-D tracks in 2-D plane

Usage

plot2d(
  origTrack,
  simTrack = NULL,
  titleText = character(1),
  DEM = NULL,
  BG = NULL,
  padding = 0.1,
  alpha = 0.7,
  resolution = 500
)

Arguments

Value

A ggplot2 object.

Examples

plot2d(niclas)

Description

Plot track(s) with a surface of a digital elevation model in three dimensions

Usage

plot3d(
  origTrack,
  simTrack = NULL,
  titleText = character(1),
  DEM = NULL,
  padding = 0.1,
  timesHeight = 10
)

Arguments

Value

Plots a plotly object

Examples

plot3d(niclas)

Description

The function takes either one track or two tracks. The second track can be a list of tracks (eg. the output of n.sim.cond.3d), Then the densities of turn angle, lift angle and step length of all the simulations is taken. Additionally the autodifferences parameter can be set to true, then the densities of the autodifferences in turn angle, lift angle and step length are visualized.

Usage

plot3d.densities(
  track1,
  track2 = NULL,
  autodifferences = FALSE,
  scaleDensities = FALSE
)

Arguments

Value

A ggplot2 object.

Examples

plot3d.densities(niclas)

Description

If the layout is something like matrix(c(1,2,3,3), nrow=2, byrow=TRUE), then plot 1 will go in the upper left, 2 will go in the upper right, and 3 will go all the way across the bottom.

Usage

plot3d.multiplot(..., plotlist = NULL, cols = 1, layout = NULL)

Arguments

Value

Nothing, plots the ggplot2 objects.

Examples

plot3d.multiplot(plot2d(niclas), plot2d(niclas), plot2d(niclas))

Description

Creates a three dimensional scatterplot of the possibles next steps, based on the tldCube, which was extracted from a track.

Usage

plot3d.tldCube(tldCube)

Arguments

Value

Plots a plotly object

Examples

P <- get.track.densities.3d(niclas)
suppressWarnings(plot3d.tldCube(P$tldCube))

Description

Plots a rasterLayer or rasterStack

Usage

plotRaster(r, title = character(0), centerColorBar = FALSE, ncol = NULL)

Arguments

Value

Plots the rasters

Examples

plotRaster(dem)

Description

Calculates the Q probability, representing the pull to the target. The number of steps on which the Q prob will be quantified is number of total segments less than one (the last step is defined by the target itself).

Usage

qProb.3d(sim, n.locs, parallel = FALSE, maxBin = 25)

Arguments

Value

A list containing the Q - tldCubes for every step

Examples

qProb.3d(niclas, 3)

Description

Simulates n tracks with the geometrical properties of the original track, between the same start and end point.

Usage

reproduce.track.3d(
  track,
  n.sim = 1,
  parallel = FALSE,
  error = TRUE,
  DEM = NULL,
  BG = NULL,
  filterDeadEnds = TRUE,
  plot2d = FALSE,
  plot3d = FALSE,
  maxBin = 25,
  gradientDensity = TRUE
)

Arguments

Value

A list or data.frame containing the simulated track(s) (CERW).

Examples

reproduce.track.3d(niclas[1:10, ])

Description

Exports a dataCube of type rasterStack as Tiff image sequence. Image sequences are a common structure to represent voxel data and most of the specific software to visualize voxel data is able to read it (e.g. blender)

Usage

saveImageSlices(rStack, filename, dir, NaVal = 0)

Arguments

Value

Saves the Tiff image files.

Examples

crws <- lapply(X = seq(1:100), FUN = function(X) {
  sim.crw.3d(nStep = 100, rTurn = 0.99, rLift = 0.99, meanStep = 0.1)
})
points <- do.call("rbind", crws)
extent <- raster::extent(c(-10, 10, -10, 10))
ud <- voxelCount(points, extent,
  xyRes = 5,
  zMin = -10, zMax = 10, standartize = TRUE
)
saveImageSlices(ud, filename = "saveImageSlices_test", dir = tempdir())

Description

Converts a sf data.frame to a normal dataframe

Usage

sf2df.3d(track)

Arguments

Value

A data.frame.

Examples

sf2df.3d(track2sf.3d(niclas, CRS = 4326))

Description

Creates a conditional empirical random walk, with a specific starting and ending point, geometrically similar to the initial trajectory (extractMethod: raster overlay method can take "simple" or "bilinear")

Usage

sim.cond.3d(
  n.locs,
  start = c(0, 0, 0),
  end = start,
  a0,
  g0,
  densities,
  qProbs,
  error = FALSE,
  DEM = NULL,
  BG = NULL
)

Arguments

Value

A trajectory in the form of data.frame

Examples

niclas <- track.properties.3d(niclas)
n.locs <- 3
P <- get.track.densities.3d(niclas)
f <- 1500
start <- Reduce(c, niclas[1, 1:3])
end <- Reduce(c, niclas[n.locs, 1:3])
a0 <- niclas$a[1]
g0 <- niclas$g[1]
uerw <- sim.uncond.3d(
  n.locs * f, start = start, a0 = a0, g0 = g0, densities = P
)
Q <- qProb.3d(uerw, n.locs)
sim.cond.3d(
  n.locs = n.locs, start = start, end = end,
  a0 = a0, g0 = g0, densities = P, qProbs = Q
)

Description

Simulation of a three dimensional Correlated Random Walk

Usage

sim.crw.3d(nStep, rTurn, rLift, meanStep, start = c(0, 0, 0))

Arguments

Value

A trajectory in the form of data.frame

Examples

sim.crw.3d(nStep = 10, rTurn = 0.9, rLift = 0.9, meanStep = 1, start = c(0, 0, 0))

Description

Creates a conditional empirical random walk in gliding mode, between a start and end point. The walk is performed on a MODE layer and, if provided, additionally on a background and digital elevation layer. The gliding is simulated with sim.cond.3d and soaring with sim.uncond.3d, therefore soaring is not restricted towards the target and can happen completly free as long as there are good thermal conditions. It is important to extract for every mode in the MODE raster layer a corresponding densities object with get.densities.3d and pass them to the function.

Usage

sim.glidingSoaring.3d(
  MODE,
  dGliding,
  dSoaring,
  qGliding,
  start = c(0, 0, 0),
  end = start,
  a0,
  g0,
  error = TRUE,
  smoothTransition = TRUE,
  glideRatio = 15,
  DEM = NULL,
  BG = NULL,
  verbose = FALSE
)

Arguments

Value

A 'soaring-gliding' trajectory in the form of data.frame

Note

The MODE raster layer must be in the following structure: Gliding pixels have the value 1 and soaring pixel the values 2. NA's are not allowed in the raster.

Examples

print("tbd.")

Description

This function creates unconditional walks with prescribed empirical properties (turning angle, lift angle and step length and the auto-differences of them. It can be used for uncon- ditional walks or to seed the conditional walks with comparably long simulations. The conditional walk connecting a given start with a certain end point by a given number of steps needs an attraction term (the Q probability, see qProb.3d) 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. Creates a unconditional empirical random walk, with a specific starting point, geometrically similar to the initial trajectory.

Usage

sim.uncond.3d(n.locs, start = c(0, 0, 0), a0, g0, densities, error = TRUE)

Arguments

Value

A 3 dimensional trajectory in the form of a data.frame

Note

Simulations connecting start and end points with more steps than 1/10th or more of the number of steps of the empirical data should rather rely on simulated unconditional walks with the same properties than on the empirical data (factor = 1500).

Random initial heading

For a random initial heading a0 use: sample(atan2(diff(coordinates(track)[,2]), diff(coordinates(track)[,1])),1)

Examples

sim.uncond.3d(
  10, start = c(0, 0, 0), a0 = pi / 2, g0 = pi / 2,
  densities = get.track.densities.3d(niclas)
)

Description

The test simulates a CRW with given parameters and reconstructs it by using the eRTG3D

Usage

test.eRTG.3d(
  parallel = FALSE,
  returnResult = FALSE,
  plot2d = FALSE,
  plot3d = TRUE,
  plotDensities = TRUE
)

Arguments

Value

A list containing the original CRW and the simulated track (CERW).

Examples

test.eRTG.3d()

Description

Uses two-sample Kolmogorov-Smirnov test or the one-sample t-test to compare the geometric characteristics of the original track with the characteristics of the simulated track.

Usage

test.verification.3d(track1, track2, alpha = 0.05, plot = FALSE, test = "ks")

Arguments

Value

Test objects of the 6 two-sample Kolmogorov-Smirnov test conducted.

Note

By choosing test = "ttest" a random sample, without replacement is taken from the longer track, to shorten it to the length of the longer track. The order of the shorter track is also sampled randomly. Then the two randomly ordered vectors of turn angles, lift angles and step lengths are substracted from each other. If the both tracks stem from the same distributions the the mean deviatio should tend to towards zero, therefore the difference is tested two-sided against mu = 0 with a one-sample t-test.

By setting test = "ks" a two-sample Kolmogorov-Smirnov test is carried out on the distributions of turn angles, lift angles and step lengths of the two tracks.

Examples

test.verification.3d(niclas, niclas)

Description

Extent of track(s)

Usage

track.extent(track, zAxis = FALSE)

Arguments

Value

Returns an extent object of the raster package in the 2–D case and a vector in the 3–D case.

Examples

track.extent(niclas, zAxis = TRUE)

Description

Returns the properties (distances, azimuth, polar angle, turn angle & lift angle) of a track in three dimensions.

Usage

track.properties.3d(track)

Arguments

Value

The data.frame with track properties

Examples

track.properties.3d(niclas)

Description

The length of timeLag must be the the track's length minus 1 and represents the time passed between the fix point acquisition

Usage

track.split.3d(track, timeLag, lag = NULL, tolerance = NULL)

Arguments

Value

A list containing the splitted tracks.

Examples

track.split.3d(
  niclas,
  timeLag = rep(1, nrow(niclas) - 1) + rnorm(nrow(niclas) - 1,
  mean = 0,
  sd = 0.25)
)

Description

Converts a track to a 'sf, data.frame'

Usage

track2sf.3d(track, CRS = NA)

Arguments

Value

A track of type 'sf, data.frame'.

Examples

track2sf.3d(niclas, 4326)

Description

Attention: Please use this function for CRS transformations, since it is based on the st_transform from the sf package and therefore supports CRS transformations in 3-D. Note: spTransform from the sp package only supports transformations in the 2D plane, which will cause distortions in the third dimension.

Usage

transformCRS.3d(track, fromCRS, toCRS)

Arguments

Value

A data.frame containing x,y,z and variables.

Examples

transformCRS.3d(niclas, fromCRS = 2056, toCRS = 4326)

Description

Calculates the turn angle between every point in the track and the last point (target).

Usage

turn2target.3d(track)

Arguments

Value

A numeric vector with the turn angles to target

Examples

turn2target.3d(niclas)

Description

Derives a three dimensional distribution of a turn angle, lift angle and step length, using the Freedman–Diaconis rule for estimating the number of bins.

Usage

turnLiftStepHist(
  turn,
  lift,
  step,
  printDims = TRUE,
  rm.zeros = TRUE,
  maxBin = 25
)

Arguments

Value

A three dimensional histogram as data.frame

Examples

niclas <- track.properties.3d(niclas)[2:nrow(niclas), ]
turnLiftStepHist(niclas$t, niclas$l, niclas$d)

Description

A rasterStack object is created, representing the 3–D voxel cube. The z axis is sliced into regular sections between the maximum and minimum value. For every height slice a raster with points per cell counts is created. Additionally the voxels can be standartized between 0 and 1.

Usage

voxelCount(
  points,
  extent,
  xyRes,
  zRes = xyRes,
  zMin,
  zMax,
  standartize = FALSE,
  verbose = FALSE
)

Arguments

Value

A rasterStack object, representing the 3–D voxel cube.

Examples

voxelCount(niclas, raster::extent(dem), 100, 100, 1000, 1400, standartize = TRUE)