identify_migrations {MigrationDetectR}

identify_migrations

Description

identify_migrations

Usage

identify_migrations(
  segs,
  locs,
  min_res_length = 90,
  occurrence_locs = NULL,
  occurrence_times = NULL,
  verbose = TRUE
)

Arguments

segs

A vector of interval, a vector of intervals which indicate residence segments, such as detected by detect_segments.

locs

A vector of Character, locations which correspond to segs.

min_res_length

(Optional) Numeric. A vector of days indicating the minimum number of days for segs to quality as viable origin or destination of a migration. Default is 90.

occurrence_locs

(Optional) Character. See occurrence_times

occurrence_times

(Optional) If provided along with the matching occurrence_times, will try to find the optimal point in time during which the migration occurred.

verbose

(Optional) logical. Output optional messages? Default is TRUE.

Value

A tibble containing the detected true relocations, if any. Contains the fields:

• from Character, the location from which the relocations started.

• to Character, the location from which the relocations started.

• movement_interval interval of the transitionary period, starting with the end of the prior residency and ending with the start of the new residency.

• movement_length The duration of the transitionary period in seconds.

• movement_midrange The midpoint of the transitionary period.

If occurrence_locs and occurrence_times were provided, find_best_split will be used to detect the optimum split time, and the following columns will be added:

• split_time, a POSIXct which indicates the time of the optimal split.

• split_correctness, a numeric which as a quality measure of splot_time reports the split's ratio of wrongly assigned days to the correctly assigned days.

Author(s)

Johannes Mast [e-mail], based on the algorithm by Guanghua Chi [e-mail]

References

Chi, Guanghua, Fengyang Lin, Guangqing Chi, and Joshua Blumenstock. 2020. “A General Approach to Detecting Migration Events in Digital Trace Data.” Edited by Song Gao. PLOS ONE 15 (10): e0239408. https://doi.org/10.1371/journal.pone.0239408.

Examples

trace <- MigrationDetectR::example_trace
# Detect segments
segments <-
  detect_segments(
      locs = trace$location,
      times = trace$timestamp,
      param_min_days = 3,
      param_prop_days = 0.06,
      param_window_size_days = 7)
 nrow(segments) # check the number of detected segments

 migrations <-
 identify_migrations(
  segs = segments$segments,
  locs = segments$locs,
  min_res_length = 90,
  occurrence_locs = trace$location,
  occurrence_times = trace$timestamp
  )
  nrow(migrations) # check the number of identified migrations
  head(migrations) # check the detected migrations