Cluster a movement track into spatiotemporal clusters

cluster_track that assigns a cluster id to each location in a ctdf by running a multi-step pipeline:

1. identify temporally continuous putative regions via slice_ctdf().

2. merge adjacent putative regions with intersecting convex hulls via spatial_repair().

3. locally split each putative region using DTSCAN via local_cluster_ctdf() and sf_dtscan().

4. enforce non-overlap in time by merging any putative regions with overlapping time domains via temporal_repair().

5. drop small clusters and run additional spatial and track-shape repairs via spatial_repair() and tail_repair().

6. optionally merge adjacent clusters within aggregate_dist via aggregate_ctdf().

Usage

cluster_track(
  ctdf,
  deltaT = 30,
  nmin = 3,
  minCluster = 3,
  area_z_min = 1,
  length_z_min = 1,
  trim = 0.05,
  aggregate_dist
)

Arguments

ctdf

A ctdf object (see as_ctdf()).

deltaT

Numeric; passed to slice_ctdf(). Maximum allowable time gap (in days) used when splitting candidate regions into movement segments.

nmin

Integer; passed to slice_ctdf() (nmin) and local_cluster_ctdf() (nmin).

minCluster

Integer; minimum number of points required to keep a putative cluster (clusters with N <= minCluster are dropped before final repairs).

area_z_min

Numeric; pruning threshold forwarded to local_cluster_ctdf() and ultimately sf_dtscan() as area_z_min (sign is flipped internally).

length_z_min

Numeric; pruning threshold forwarded to local_cluster_ctdf() and ultimately sf_dtscan() as length_z_min (sign is flipped internally).

trim

Numeric; passed to temporal_repair(). Maximum fraction trimmed from each tail when estimating each cluster's time domain.

aggregate_dist

Optional numeric; if supplied, passed to aggregate_ctdf() as dist (numeric treated as km).

Value

Invisibly returns ctdf, with cluster updated in-place and attr(ctdf, "cluster_params") set.

Details

The function updates ctdf by reference and stores its parameters in attr(ctdf, "cluster_params").

See also

as_ctdf(), slice_ctdf(), spatial_repair(), local_cluster_ctdf(), sf_dtscan(), temporal_repair(), tail_repair(), aggregate_ctdf()

Examples

data(mini_ruff)
ctdf = as_ctdf(mini_ruff) |> cluster_track()

if (requireNamespace("clusterTrack.Vis" )) {
  clusterTrack.Vis::map(ctdf)
}
#> Loading required namespace: clusterTrack.Vis
if (FALSE) { # \dontrun{
data(pesa56511)
pesa = as_ctdf(pesa56511, time = "locationDate") |> cluster_track()

if (requireNamespace("clusterTrack.Vis" )) {
  clusterTrack.Vis::map(pesa)
}

data(ruff143789)
ruff = as_ctdf(ruff143789, time = "locationDate") |> cluster_track()

if (requireNamespace("clusterTrack.Vis" )) {
  clusterTrack.Vis::map(ruff)
}

data(lbdo66862)
lbdo = as_ctdf(lbdo66862, time = "locationDate") |> cluster_track()

if (requireNamespace("clusterTrack.Vis" )) {
  clusterTrack.Vis::map(lbdo)
}

} # }