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 spatially overlapping adjacent putative regions via spatial_repair()

3. locally cluster each putative region using DTSCAN via local_cluster_ctdf()

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

5. drop small or false putative clusters and run additional spatial repairs via spatial_repair()

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

Usage

cluster_track(
  ctdf,
  nmin = 3,
  z_min = 1,
  trim = 0.05,
  minCluster = 3,
  deltaT,
  aggregate_dist,
  trace = FALSE
)

Arguments

ctdf

A ctdf object (see as_ctdf()).

nmin

Integer; local DTSCAN support threshold. Passed to local_cluster_ctdf() as nmin, then to sf_dtscan() as min_pts, where it defines the minimum effective Delaunay-neighbour count for a core site.

z_min

Numeric; pruning strictness in SD units. Smaller values produce more compact clusters and often more unassigned points. Implementation detail: the underlying thresholds use an inverse z-score convention, so the sign is flipped internally; see sf_dtscan() and local_cluster_ctdf().

trim

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

minCluster

Integer; post-clustering pruning threshold. Putative clusters with N <= minCluster are dropped.

deltaT

Optional numeric; passed to slice_ctdf(). Maximum allowable time gap (in days).

aggregate_dist

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

trace

Logical; if TRUE, store intermediate .putative_cluster labels from the cluster_track() pipeline in attr(ctdf, "putative_cluster_trace").

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(), aggregate_ctdf()

Examples

data(mini_ruff)
x = as_ctdf(mini_ruff) |> cluster_track()
#> → Find putative cluster regions.
#> ! Repairing[1]...
#> → Local clustering.
#> ! Repairing[2]...
#> ! Compute lof scores...

if (FALSE) { # \dontrun{
data(pesa56511)
pesa = as_ctdf(pesa56511, time = "locationDate") |> cluster_track()

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

data(ruff07b5)
ruff2 = as_ctdf(ruff07b5, time = "timestamp") |> cluster_track()

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

data(nola125a)
nola = as_ctdf(nola125a, time = "timestamp") |> cluster_track()


} # }