# Compute s vs. proportion-time-selected hulls table

### 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` |
A vector of indices of the points to use as samples |

`sinit` |
The initial value of |

`ptsh.target` |
A vector of values 0..1 that will serve as the target |

`ptsh.max` |
The highest value of ptsh for which a value of |

`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, |

`time.term` |
The space-time transformation to use in the TSD distance metric: |

`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 |

`use.pb.n` |
The sample size (i.e., |

`ptsh.exists` |
What to do if there is already a ptsh table in the LoCoH-xy object: |

`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`