track_intersection {QuAnTeTrack}R Documentation

Calculate intersection metrics in tracks

Description

track_intersection() calculates the number of unique intersections between trajectories. The function also supports testing with simulations and different permutation procedures for the coordinates of the simulated trajectories' origins to compute p-values. This allows for a robust assessment of the intersection metrics, enabling users to evaluate the significance of the observed intersections in relation to simulated trajectories.

Usage

track_intersection(
  data,
  test = NULL,
  H1 = NULL,
  sim = NULL,
  origin.permutation = NULL,
  custom.coord = NULL
)

Arguments

data

A track R object, which is a list consisting of two elements:

  • Trajectories: A list of interpolated trajectories, where each trajectory is a series of midpoints between consecutive footprints.

  • Footprints: A list of data frames containing footprint coordinates, metadata (e.g., image reference, ID), and a marker indicating whether the footprint is actual or inferred.

test

Logical; if TRUE, the function compares the observed intersection metrics against. Default is FALSE.

H1

A character string specifying the alternative hypothesis to be tested. Options are "Lower" for testing whether the observed intersections are significantly lower than the simulated ones (e.g., coordinated or gregarious movement), or "Higher" for testing whether the observed intersections are significantly higher than the simulated ones (e.g., predatory or chasing events).

sim

A track simulation R object consisting of a list of simulated trajectories to use for comparison when test = TRUE.

origin.permutation

A character string specifying the method for permutation of the coordinates of the simulated trajectories' origins. Options include "None", "Min.Box", "Conv.Hull", or "Custom". Default is "None".

custom.coord

A matrix of custom coordinates that define the vertices of an area for permutation of the coordinates of the simulated trajectories' origins.

Details

The track_intersection() function is designed to calculate the number of unique intersections between trajectories and to evaluate their statistical significance through hypothesis testing based on simulated tracks. This process provides a robust framework for comparing observed intersections against those expected under random conditions, allowing users to test specific behavioral hypotheses related to the movement patterns of trackmakers.

Hypothesis testing is controlled by the H1 argument, which defines the alternative hypothesis to be evaluated. This argument is crucial for interpreting the statistical results, as it determines whether the function will test for reduced or increased intersection counts compared to simulated trajectories.

The H1 argument accepts two possible values:

The selection of the H1 argument must be consistent with the behavioral hypothesis being tested. For example, use "Lower" when investigating group movement or cooperative behavior, and "Higher" when analyzing predatory or competitive interactions. The function will automatically adjust the calculation of p-values to reflect the selected H1. If the argument is left NULL, an error will be triggered, indicating that users must explicitly specify the hypothesis to be tested.

The interpretation of the combined p-value returned by the function is directly influenced by the choice of H1, as it determines whether the statistical comparison aims to detect a reduction or an increase in intersection counts compared to the simulated dataset.

In addition to hypothesis testing, the track_intersection() function offers several options for altering the initial positions of simulated tracks through the origin.permutation argument. The available options include:

The choice of origin.permutation should reflect the nature of the behavioral hypothesis being tested. For example, using "None" is most appropriate when testing how intersections compare under scenarios where trackmakers originate from specific locations. In contrast, options like "Min.Box", "Conv.Hull", or "Custom" are suitable when evaluating how intersections would differ if the tracks originated from a broader or predefined area.

The track_intersection() function also allows for integration with similarity metrics computed using simil_DTW_metric() and simil_Frechet_metric(). This combination of intersection counts and similarity metrics can provide a more comprehensive analysis of how trackmakers interacted, whether their movements were coordinated or independent, and whether their interactions were consistent with the hypothesized behavioral patterns.

Overall, the selection of H1 and origin.permutation should be carefully considered in light of the specific hypotheses being tested. By combining intersection metrics with similarity measures, users can obtain a deeper understanding of the behavioral dynamics underlying the observed trackways.

Value

A track intersection R object consisting of a list containing the following elements:

Intersection_metric

A matrix of unique intersection counts between trajectories. Each entry represents the number of unique intersection points between the corresponding pair of trajectories.

Intersection_metric_p_values

(If test = TRUE) A matrix of p-values associated with the intersection metrics, calculated through permutations of simulated trajectory origins. Each entry reflects the probability of observing an intersection count as extreme as the observed one, given the null hypothesis of no difference.

Intersection_metric_p_values_combined

(If test = TRUE) A numeric value representing the combined p-value for all intersections, indicating the overall significance of the intersection metrics across all pairs of trajectories.

Intersection_metric_simulations

(If test = TRUE) A list containing matrices of intersection counts for each simulation iteration, allowing for further inspection of the distribution of intersections across multiple randomized scenarios.

Logo

Logo.png

Author(s)

Humberto G. Ferrón

humberto.ferron@uv.es

Macroevolution and Functional Morphology Research Group (www.macrofun.es)

Cavanilles Institute of Biodiversity and Evolutionary Biology

Calle Catedrático José Beltrán Martínez, nº 2

46980 Paterna - Valencia - Spain

Phone: +34 (9635) 44477

See Also

tps_to_track, simulate_track, simil_DTW_metric, simil_Frechet_metric

Examples

# Example 1: Intersection metrics in the PaluxyRiver dataset.
s1 <- simulate_track(PaluxyRiver, nsim = 5, model = "Directed")
int1 <- track_intersection(PaluxyRiver, test = TRUE, H1 = "Lower", sim = s1,
  origin.permutation = "None")
print(int1)

# Example 2: Using "Min.Box" origin permutation in PaluxyRiver dataset.
s2 <- simulate_track(PaluxyRiver, nsim = 5, model = "Constrained")
int2 <- track_intersection(PaluxyRiver, test = TRUE, H1 = "Lower", sim = s2,
  origin.permutation = "Min.Box")
print(int2)

# Example 3: Using "Conv.Hull" origin permutation in PaluxyRiver dataset.
s3 <- simulate_track(PaluxyRiver, nsim = 5, model = "Unconstrained")
int3 <- track_intersection(PaluxyRiver, test = TRUE, H1 = "Lower", sim = s3,
  origin.permutation = "Conv.Hull")
print(int3)

# Example 4: Using "Min.Box" origin permutation in MountTom subset.
sbMountTom <- subset_track(MountTom, tracks = c(1, 2, 3, 4, 7, 8, 9, 13, 15, 16, 18))
s4 <- simulate_track(sbMountTom, nsim = 5)
int4 <- track_intersection(sbMountTom, test = TRUE, H1 = "Higher", sim = s4,
  origin.permutation = "Min.Box")
print(int4)

# Example 5: Customized origin permutation in MountTom subset.
sbMountTom <- subset_track(MountTom, tracks = c(1, 2, 3, 4, 7, 8, 9, 13, 15, 16, 18))
s5 <- simulate_track(sbMountTom, nsim = 5)
area_origin <- matrix(c(50, 5, 10, 5, 10, 20, 50, 20), ncol = 2, byrow = TRUE)
int5 <- track_intersection(sbMountTom, test = TRUE, H1 = "Higher", sim = s5,
  origin.permutation = "Custom", custom.coord = area_origin)
print(int5)


[Package QuAnTeTrack version 0.1.0 Index]