attack_model models the visual aspects of an attack by a predator on a prey

Using parameters such as predator size, speed, shape etc. this function models the visual aspects of an attack by the predator on a prey. From the prey's perspective it calculates the visual angle of the attacker (alpha, or α) in radians, and the rate of change of this angle (dα/dt in radians/s), as well as distance and time to capture.

attack_model(speed, model_length = NULL, frequency = 60, body_length =
 NULL, body_width_v = NULL, body_width_h = NULL, profile_v = NULL, profile_h
 = NULL, max_width_loc_v = NULL, max_width_loc_h = NULL, width_filter =
 "mid", simple_output = TRUE, plot = TRUE, plot_from = 0, plot_to = NULL,
 alpha_range = NULL, dadt_range = NULL)

Arguments

speed

numeric. Either a single constant speed value or vector of speeds at the same frequency in Hz as frequency. Must be same unit as body_length per second. If a data.frame is entered the first colummn is used. For a constant speed value the function will repeat this the required number of times at the correct frequency based on model_length.

model_length

integer. Total length of the model in rows. Required if speed is a single value, in which case along with frequency it determines the distance the predator starts at. If speed is a vector model_length can be left NULL, in which case it is assumed the predator reaches the prey on the last value, and the length of the speed vector determines total length of model. Alternatively, model_length can be used to set a different capture point along the speed vector, in which case its value must be less than the total length of speed.

frequency

numeric. Frequency (Hz) of the model, i.e. how many speed and other measurements per second. Must be same frequency in Hz as speed.

body_length

numeric. Length of the attacker. Must be same units as body_width_v and body_width_h, and that used in speed.

body_width_v

numeric. Maximum width of the attacker in the vertical plane.

body_width_h

numeric. Maximum width of the attacker in the horizontal plane.

profile_v

numeric. A vector describing the shape of the attacker in the vertical plane. See details.

profile_h

numeric. A vector describing the shape of the attacker in the horizontal plane. See details.

max_width_loc_v

numeric. Location of the maximum girth in the vertical plane of the predator along the body, if not provided as part of the body profile inputs. See details.

max_width_loc_h

numeric. Location of the maximum girth in the horizontal plane of the predator along the body, if not provided as part of the body profile inputs. See details.

width_filter

string. Filters apparent widths between vertical and horizontal planes for each row of the model in various ways. See details.

simple_output

logical. Choose structure of output. If TRUE, a simple data frame of the model is returned, otherwise output is a list object given an attack_model class, and containing the final model, input parameters, subset regions, and more.

plot

logical. Choose to plot result.

plot_from

numeric. Time on x-axis to plot from.

plot_to

numeric. Time on x-axis to plot to.

alpha_range

numeric. Vector of two values of alpha. Optional. These will appear on any plot as a blue region, and if simple_output = FALSE, this region of the model is subset out to a separate entry in the saved list object. If any are not reached in the scenario there should be a message. If upper range is not reached, it is plotted from lower value to end of model, i.e. model_length location.

dadt_range

numeric. Vector of two values of alpha. Optional. These will appear on any plot as a green region, and if simple_output = FALSE, this region of the model is subset out to a separate entry in the saved list object. If any are not reached in the scenario there should be a message. If upper range is not reached, it is plotted from lower value to end of model, i.e. model_length location.

Details

Information on inputs:

Input units

speed should be in the same units as body measurements (length, width etc.) per second, e.g. cm/s. It can be either a single, constant speed value or a vector of speeds (at the correct frequency). If a single value, model_length is required in order to calculate the distance the predator starts the attack from. For example, at a frequency of 60 Hz and model_length of 180, the model will be three seconds in duration. Therefore, at a constant speed of 600 cm/s, the predator will start from approximately 1800 cm away.

frequency is in Hz. If speed is a vector it should be at the same frequency.

model_length is required when speed is a single value, where it determines the total length of the model. It is also used to vary where on variable speed vectors the predator times reaching the prey, for example cooincident with its maximum speed, to examine how this affects factors such as dα/dt. If left as the default model_length = NULL, the model ends with the predator reaching the prey on the last speed value.

Morphology

In order to correctly model the widest apparent part of the predator, and thus α, the function requires several morphometric inputs:

Length and Width

body_length is simply the total length from nose to tail (or equivalent). body_width_v and body_width_h are the maximum body widths in the vertical (i.e. dorsal:ventral) and horizontal (left:right) planes of the body. These must all be in the same units.

Body Profiles

profile_v and profile_h are vectors of widths of the predator's body as a proportion of the maximum width going from the anterior (nose) to the posterior (tail). Therefore, they should generally start and end on zero (though they don't have to), and all values must be between zero and 1. They must be regularly spaced, e.g. every 10\ along the body. They do not have to be the same length (i.e. resolution), though it is recommended they are. The longer (i.e. higher resolution) these measurements are, the better their representation of the morphology of the animal. Actual values of width along the body are calculated to the resolution of the entered unit of body_length by linearly interpolating between each proportional width. For example, if the predator body_length is 1000cm, a width value in cm is calculated at every cm along the body by interpolating between the proportional widths. Therefore, use units which will give an appropriate resolution, at least greater than the profile vector lengths. The higher the numeric value of the body_length the better, at least three digits is recommended.

You do not need to enter both profile_v and profile_h, only one is required; if one is left NULL the model will use the other to calculate α. This can be useful if your predator is always wider in one plane than the other.

The function calculates the widest apparent width of any part of the predator's body from the prey's perspective at each iteration of the model, in both planes. This is usually the maximum width of the predator, but it also depends on the predator's shape. At close distances, more anterior parts of the predator will appear to be wider, and so result in a higher α value.

Note: no section of the body posterior of the maximum width can ever show a larger apparent visual α than the maximum width. Therefore, the function only really needs profile data from the maximum width forward. However, it is important for the function to work correctly that a full, evenly spaced profile is provided. Having said that, the proportional width values posterior of the max width can be placeholder values and it will not affect calculated α, as long as they are less than 1 and spaced correctly.

Filtering of maximum apparent width between body planes

Apparent widths are calculated for both body planes, if two are entered. Which width at each body segment (e.g. horizontal or vertical) used to calculate α is determined via the width_filter operator. This can be the midpoint value between them ("mid", the default), maximum value ("max"), or minimum value ("min"). You can also choose to use only the vertical or horizontal profile widths exclusively ("v", "h"). You can also choose to use the predator's maximum width in either plane (max_width_v, max_width_h) to calculate α, in which case all other segments of the body are ignored, and only α of the maximum width is determined.

max_width_loc_v and max_width_loc_h are the locations of the maximum widths of the predator occur along the body as a proportion of the total body length going from the anterior. They are only necessary if they are not specified as one of the proportional widths in profile_v and profile_h, that is none of these have the value of exactly 1. They can also occur at an intermediate section of the body, not included as part of the body profiles.

Output

By default simple_output = TRUE the output is a data frame with every row representing a single instance (frame) of the model at the set frequency. The data frame contains columns for frame, speed, time, time reversed, distance of the nose of the predator, α, and dα/dt. If simple_output = FALSE the output is a list() object given class attack_model containing the above data frame, plus inputs, subset regions (see next section), and data detailing how each alpha was calculated (interpolated profiles, locations of maximum apparent width at each frame, etc.). This option greatly increases the time the function takes to run.

Subset regions

alpha_range and dadt_range allow regions bounded by values of α and dα/dt to be subset. Both inputs are a vector of two numeric values indicating the lower and upper range of the desired α and dα/dt region. The function identifies the closest matching, first instance of these values in the $alpha and dadt columns of the model data frame. If simple_output = FALSE, these can be found as their own elements in the output list() object. If plot = TRUE these are also plotted as blue and green shaded regions, respectively.

Plotting

If plot = TRUE a plot is produced showing speed, α and dα/dt. The X range of the plot can set with plot_from and plot_to. Optional alpha_range and dadt_range can also be plotted (see above).

General

Models end when the nose (most anterior part in the profiles) of the predator reaches the prey (last row of the data.frame, where time and distance equal zero).

At some point, the maximum girth of the predator will not make up the widest apparent visual angle of the predator, but more anterior segments will appear to the prey to be wider, and have a higher α. After interpolation of body profiles, filtering of apparent widths (see above), and identification of maximum apparent width at each iteration of the model, these final widths and their relative distances from the observing prey are used to calculate the viewing angle, α, and used to calculate the rate of change in α, dα/dt in radians/s.