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)
| speed | numeric. Either a single constant speed value or vector of speeds
at the same frequency in Hz as |
|---|---|
| model_length | integer. Total length of the model in rows. Required if
|
| frequency | numeric. Frequency (Hz) of the model, i.e. how many speed and
other measurements per second. Must be same frequency in Hz as
|
| body_length | numeric. Length of the attacker. Must be same units as
|
| 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 |
| 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 |
| dadt_range | numeric. Vector of two values of alpha. Optional. These will
appear on any plot as a green region, and if |
Information on inputs:
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.
In order to correctly model the widest apparent part of the predator, and thus α, the function requires several morphometric inputs:
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.
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.
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.
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.
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.
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).
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.