mt_stack: Combine multiple `move2` objects into one

Description

This function does a similar job to dplyr::bind_rows(), when columns are missing of any of the objects, they are added.

Usage

mt_stack(
  ...,
  .track_combine = c("check_unique", "merge", "merge_list", "rename"),
  .track_id_repair = c("unique", "universal", "unique_quiet", "universal_quiet")
)

Value

An object of the class move2

Arguments

...: Either a list of move2 objects to combine or the objects to combine as separate arguments
.track_combine: A character string indicating the way duplicated tracks should be resolved. By default ("check_unique") an error is raised if different objects contain tracks with the same name. With "merge" and "merge_list" tracks with the same name can be merged, and with "rename" non unique tracks can be renamed.
.track_id_repair: The way in which names should be repaired when renaming is done, see vctrs::vec_as_names() for more details on each option

Details

An attempt is made to combine objects that have a different track_id_column or time_column, however this is only done if it can be done without data loss.

When objects are too different (e.g. different projection or different types of time columns that cannot be combine) and error is raised. When tracks have the same name in different objects to combine this will results in an error.

When merging several tracks, the track attributes of these tracks are also combined. For track data this can result in conflicts. With "merge" unique values are selected if not one unique value is present a warning is raised. With "merge_list" a list column is created for each track attribute that can be summarized later.

Examples

Run this code

a <- mt_sim_brownian_motion(1:2, tracks = c("a", "b"))
b <- mt_sim_brownian_motion(1:2, tracks = c("g", "h"))
mt_stack(a, b)

## having different columns does not cause problems
a$extra_data <- 1:nrow(a)
mt_stack(list(a, b))

## Combining different datasets works
fishers <- mt_read(mt_example(), n_max = 100, col_select = c(
  "eobs:used-time-to-get-fix",
  "location-long", "location-lat", "timestamp", "individual-local-identifier"
))

## Objects to stack need to have the same CRS, use either st_set_crs
## or st_transform depending what is appropriate
random_track <- mt_sim_brownian_motion(
  t = as.POSIXct("1970-1-1") + 1:3,
  tracks = factor(letters[1:2])
) |> sf::st_set_crs(4326)
mt_time(random_track) <- "timestamp"
mt_stack(
  random_track,
  fishers
)
track_1 <- mt_sim_brownian_motion(tracks = letters[1:3], t = 1:3) |>
  mutate_track_data(sex = "f")
track_2 <- mt_sim_brownian_motion(tracks = letters[3:4], t = 4:6) |>
  mutate_track_data(sex = c("f", "m"))
mt_stack(track_1, track_2,
  .track_combine = "merge_list"
)
mt_stack(track_1, track_2,
  .track_combine = "merge"
)
# \donttest{
if (requireNamespace("units")) {
  males <- tail(filter_track_data(
    fishers,
    grepl("M", `individual-local-identifier`)
  ), 5)
  females <- filter_track_data(
    fishers,
    grepl("F", `individual-local-identifier`)
  )
  females$`eobs:used-time-to-get-fix` <- units::set_units(
    females$`eobs:used-time-to-get-fix`,
    "hours"
  )
  females <- tail(females, 5)
  ## combining with different units works correctly (units are unified with correct conversion)
  mt_stack(males, females)
}
# }