BaBA: Barrier Behavior Analysis (BaBA)

In wx-ecology/BaBA: Barrier Behavior Analysis (BaBA)

Barrier Behavior Analysis (BaBA)

Description

This function classifies animal movement near linear barriers into 6 different behavioral categories: quick cross, average movement, bounce, back-and-forth, trace, and trapped. The classification unit of BaBA first identifies 'encounter events', defined by a series of continuous locations that fall within the barrier buffers. Each event will then be classified into one of the 6 barrier behaviors. Even though many arguments have default settings, we recommend users adjust these values to best fit the ecology and management goals of the studied species.

Usage

BaBA(animal, barrier, d,
interval = NULL, b_time = 4, p_time = 36, w = 168, tolerance = 0, units = "hours",
max_cross = 0,  sd_multiplier = 1, exclude_buffer = F, round_fixes = F, 
export_images = F, img_path = "event_imgs", img_suffix = NULL)

Arguments

animal	An sf POINT object representing animal telemetry locations with a column named "Animal.ID" that identifies each individual; a column named "date" in "POSIXct" format. CRS has to be the same as barrier, preferably in a projected UTM coordinate system. More see Details.
barrier	An sf LINESTRING or MULTILINESTRING object showing barrier locations in the area overlapped with animal movement data. In the same spatial projection as animal.
d	Barrier buffer size in meters if barrier has a projected coordinate system CRS, in the units of barrier otherwise.
interval	Time interval of the movement data (unit specified in units). If not specified, BaBA will use the most frequent time difference between steps as interval, which might affect result accuracy if the data has an irregular time interval or a lot of missing data.
b_time	Maximum duration, in the same unit as interval, that an encounter event would be considered as a short event ('bounce' or 'quick cross'). Must be evenly divisible by interval
p_time	Minimum duration, in the same unit as interval, that an encounter event would be considered as a 'trapped' condition. Must be evenly divisible by interval.
w	The length of time, in the same unit as interval, to include around the encounter event to calculate average movement straightness using a moving window. Locations included are all locations within w/2 before the first location of the encounter event and w/2 after the last location of the event. More see Details.
tolerance	The maximum duration, in the same unit as interval, to allow points that are outside of barrier buffer but between 2 sets of points within the buffer to be included, so that all points are considered as one continous encounter event. Useful when movement data has a very high temporal resolution. Must be evenly divisible by interval.
units	The temporal units of interval, b_time, p_time, w, and tolerance. One of "secs", "mins", "hours", "days", and "weeks".
max_cross	The maximum number of crosses in an encounter event allowed for in tracing and back-and-forth behavior. More see Details.
sd_multiplier	A numeric value to determine the numbers of standard deviations used that defines the normal range of movement straightness. Default is 1. More in Details.
exclude_buffer	Logical. Whether to consider movement locations within barrier buffers when calculating average movement straightness. More see Details.
round_fixes	Logical. Indicates whether elements of the "date" column of animal should be rounded to the nearest units. This is intended to account for minor variations in fix acquisition time that may lead to some intervals being slightly longer than interval. Note that this is not a replacement for cleaning the animal data.frame and removing repetitive timesteps as described in Details.
export_images	Logical. If TRUE, will export snapshot of event locations as .png files named with the classification of the event, the Animal.ID of the animal, the burstID of the event and potential suffix specified by argument img_suffix.
img_path	When export_images is TRUE, the character name of the folder that the images should be exported to. The folder will be created in the working directory if it does not exist. Defaults to "event_imgs".
img_suffix	character to be added at the end of the naming if the images are exported when export_images is TRUE

Details

BaBA works better with cleaned animal data. Make sure your date column is cleaned so that the time difference between any step is evenly divisible by interval. It is OK to have missing steps but remove repetitive timesteps and bursts of locations smaller than interval before running BaBA.

Barrier buffer distance d represents the distance on both sides of the barrier lines within which animal movement locations are considered 'encounters' with the barrier, and continuous locations form an 'encounter event'. This might be the most important parameter to set the BaBA. The buffer distance will affect numbers and durations of trajectories identified as 'encounter events'. For species with different movement capacities or ecological attributes, barrier effect distance might be different. You can decide the distance either by a priori knowledge or testing a range of distance and compare the results.

The average straightness is compared to the straightness of a to-be-classified encounter event in order to determine whether the event is 'trace' (more straight than average), 'back-n-forth' (less straight than average), or 'normal movement' (similar to average). The reason to apply a moving window method with a width of w to calculate the average straightness is because some animal movements, such as migrations, show great seasonal variations. The moving window method calculates localized average straightness around the time when the to-be-classified encounter event occurs.

The default average straightness calculation considers movement segments w/2 days before and after the focal encoutner event, which can include movement locations within and outside of the barrier buffers. One might want to control potential impacts of barriers on movement and only calculate average movement straightness based on locatons outside of fence buffers. Use exclude_buffer to indicate whether or not to include movement locations inside barrier buffers. The default is FALSE because in the sample study fence density is relatively high and animals fall in barrier buffers much of the time. If excluded, not enough continuous locations within the time window would be outside of the buffer.

The average and standard deviation of straightness measurements calculated by the moving window method are used to define the normal range of movement straightness. Any encounter event with a straightness < (average straightness + sd_multiplier * sd straightness) would be classified as 'trace' (more straight than normal), < (average straightness - sd_multiplier * sd straightness) would be 'back-and-forth' (more tortuous than normal), and in between would be 'average movement'. To make the standard more strict for an event to be classified as not 'normal' (i.e. 'back-and-forth' or 'trace'), use a larger number for the sd_multiplier.

When the barriers are curvy or the temporal resolution of the movement data is coarse, straight lines between movement locations (movement segments) might appear to be crossing the barrier even if the locations are on the same side of the barrier. max_cross allows some numbers of intersections between movement segments and barriers to be included in the 'trace' and 'back-and-forth' behavior. When the intersections are larger than max_cross, the encounter event will be classified as 'unknown'.

Value

BaBA returns a list.

$classification

a data.frame. Each row represents one encounter event. AnimalID is the ID of the individual; burstID is the ID of the encounter event and it matches the ID of the exported images; easting and northing are the coordinates of the starting location of the encounter event; start_time, end_time, and duration describe the temporal characteristics of the encounter event; cross is the number of intersections between the encounter event trajectory and the barrier; straightness is the straightness of the encounter event trajectory and is NaN when the encounter event is 'bounce or 'quick cross'; finally, eventTYPE is the barrier behavior classification of the encounter event.

$encounters

a sf POINT object showing the locations of classified encounter events represented by the starting location.

Author(s)

Wenjing Xu [e-mail] and Valentine Herrmann [e-mail]

References

Xu W, Dejid N, Herrmann V, Sawyer H, Middleton AD. Barrier Behaviour Analysis (BaBA) reveals extensive effects of fencing on wide-ranging ungulates. J Appl Ecol. https://doi.org/10.1111/1365-2664.13806

Examples

library(BaBA)

# load sample data.
data("pronghorn")
data("fences")

# Animal data must be an "sf POINT" object created by the "sf" package. 
# individual ID column should be named "Animal.ID" and timestamp column should be named "date"
class(pronghorn)
names(pronghorn)

# run BaBA on the pronghorn data
results_prong <- BaBA(animal = pronghorn, barrier = fences, d = 110, max_cross = 4)

# View BaBA results
head(results_prong$classification)

# plot encounter event locations
plot(fences)
plot(results_prong$encounters, add = TRUE)

# write the encounters as shapefile, changing the date column to character to
# avoid the shapefile dropping the time
sf::st_write(dplyr::mutate(results_prong$encounters, date = as.character(date)),
             ".", "encountersPRONG", driver = "ESRI Shapefile")

# export event images to visually check event classifications. Using mule deer data as an example
data("muleDeer")
results_deer <- BaBA(animal = muleDeer, barrier = fences, d = 90,
  export_images = TRUE, img_suffix = "DEER")

wx-ecology/BaBA documentation built on April 13, 2025, 12:07 a.m.