Skip to contents

Cluster a movement track into spatiotemporal clusters

Source: R/cluster_track.R
cluster_track.Rd

cluster_track() identifies use sites: areas where an individual concentrates its activity during distinct periods along a movement track.

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 track is first split into provisional regions, allowing spatial clustering to adapt to local conditions. Neighbouring regions or clusters are combined when their spatial structure provides insufficient evidence for keeping them separate.

Use sites describe where and when the animal concentrated its activity, distinguishing separate visits to the same place. Optional distance-based aggregation combines nearby, temporally adjacent sites at a spatial scale chosen by the user.

The function updates ctdf by reference and stores its parameters in the cluster_params attribute.

See also

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

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


} # }