Compute s vs. proportion-time-selected hulls table

Share:

Description

Identify the values of s that result in proportion p of hulls being time-selected

Usage

1
2
3
4
5
6
7
lxy.ptsh.add(lxy, id = NULL, k = 10, n = 200, samp.idx = NULL,
  sinit = 0.005, ptsh.target = 1:9/10, ptsh.max = 0.98, ptsh.buf = 0.01,
  max.iter = 15, max.loops = 15, max.reached = c("warning", "stop")[1],
  time.term = c("vmax", "dif")[1], FNN.algorithm = c("cover_tree",
  "kd_tree", "VR", "CR")[2], use.nn = FALSE, plotme = TRUE, save = TRUE,
  nn.add = FALSE, use.pb.n = 200, ptsh.exists = c("replace", "append")[2],
  beep = FALSE, status = TRUE)

Arguments

lxy

A LoCoH-xy object

id

The name(s) of individuals to analyze

k

Value for the k-method that will be used to create hulls for the sample points (and then used to find the proportion of time-selected hulls)

n

Number of randomly selected points to use as samples (ignored if samp.idx is passed)

samp.idx

A vector of indices of the points to use as samples

sinit

The initial value of s that will be used to start the iteration to find that value of s that produces a proportion of time selected hulls >= ptsh.max

ptsh.target

A vector of values 0..1 that will serve as the target ptsh values. For each ptsh target, script will try to find a value of s that generates the targeted proportion of time selected hulls (within ptsh.buf)

ptsh.max

The highest value of ptsh for which a value of s will be computed. It is generally recommended that this be less than 1.

ptsh.buf

The level of accuracy or precison to which the found values of 's' return the targetted ptsh.

max.iter

The maximum number of times the script will double sinit in an effort to find the value of s that produces ptsh.max

max.loops

The maximum number of intermediate values of s the script will try when 'zooming' in on the target ptsh levels

max.reached

What to do if the maximum number of iterations is reached, warning or stop

time.term

The space-time transformation to use in the TSD distance metric: 'vmax' for the maximum velocity transformation (default) or 'dif' for the diffusion transformation.

FNN.algorithm

The algorithm to be used in the get.knnx() function in the package FNN

use.nn

Whether to use saved nearest neighbor sets for the ptsh computations. T/F

plotme

Whether to plot the ptsh vs. s curve. T/F

save

Whether to save the ptsh-s table in the LoCoH-xy object. T/F

nn.add

Whether to also identify and save nearest neighbor sets for all points for k=k and the values of s identified. T/F

use.pb.n

The sample size (i.e., n) above which a progress bar will be displayed

ptsh.exists

What to do if there is already a ptsh table in the LoCoH-xy object: 'replace' or 'append'

beep

Whether to beep when done. T/F

status

Display status messages. T/F

Details

When s=0, nearest neighbors are space-selected (i.e., point-to-point distance is merely Euclidean distance). For large values of s, nearest neighbors are effectively time-selected (e.g., temporally contiguous). One approach to selecting a value of s between these two ends of the spectrum is to pick a s value that returns an intermediate proportion of time-selected-hulls representing the desired balance between space and time selection (which in turn is shaped by the research question / objective). This function will find the value(s) of s that produce a desired proportion of time-selected-hulls using a randomly-selected subset of points. A general rule of thumb is to pick a value of s that results in a proportion of time-selected hulls from 0.4 to 0.6.

The script iteratively tries a variety of s values until it finds one that produces the desired proportion of time-selected hulls within a tolerance of ptsh.buf. If for example the vector of target values ptsh.target includes 0.5, and ptsh.buf = 0.01, the script will try to find a value of s that results in a proportion of time-selected hulls between 0.49 and 0.51.

See Also

lxy.nn.add

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.