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 temporally adjacent putative regions via spatial_repair().

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

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

5. drop small clusters and run additional spatial repairs via spatial_repair() and tail_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
)

Arguments

ctdf

A ctdf object (see as_ctdf()).

nmin

Integer; passed to local_cluster_ctdf() (nmin). (clusters with N <= minCluster are dropped before final repairs).

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

minCluster

Integer; minimum number of points required to keep a putative cluster used when splitting candidate regions into movement segments. tail when estimating each cluster's time domain.

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).

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)
x = as_ctdf(mini_ruff) |> cluster_track()
#> → Find putative cluster regions.
#> ! Spatial repair.
#> → Local clustering.
#> ! Temporal repair.

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)
lbdo2 = as_ctdf(lbdo66862, time = "locationDate") |> cluster_track()

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


} # }