Attack Model

Source: R/attack_model_whale.R

attack_model_whale models the visual aspects of an attack by a whale on a prey

This function is a customised version of attack_model which incorporates the unique changes to a rorqual whale's visual profile caused by it opening its huge mouth when attacking a school of prey.

It contains several additional inputs relating to the morphology of the mouth and the timings of its opening, which greatly change the whale's visual profile.

This help document only contains help on use of the inputs specific to this function. See attack_model for description of the others.

attack_model_whale(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", jaw_length = NULL, jaw_angle_upper = 0.5235988,
 jaw_angle_lower = 0.8726646, a_mouth_open = NULL, b_max_gape_start = NULL,
 c_max_gape_end = NULL, d_mouth_closed = NULL, simple_output = FALSE, 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.
jaw_length

numeric. distance of the whale's jaw 'hinge' (i.e. where upper and lower jaws meet) from the rostrum, in the same units as the body_length. See details.
jaw_angle_upper

numeric. Angle in radians off the whale's longitudnal axis of the upper jaw at maximum gape. See details.
jaw_angle_lower

numeric. Angle in radians off the whale's longitudnal axis of the lower jaw at maximum gape. See details.
a_mouth_open

integer. Iteration of the model (i.e. row, or placement along the speed profile) where the mouth starts to open. See details.
b_max_gape_start

integer. Iteration of the model (i.e. row, or placement along the speed profile) where the mouth has reached max gape. See details.
c_max_gape_end

integer. Iteration of the model (i.e. row, or placement along the speed profile) where the mouth starts to close See details.
d_mouth_closed

integer. Iteration of the model (i.e. row, or placement along the speed profile) where the mouth has fully closed. 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_whale 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

These inputs are used to calculate the apparent width to the prey of a whale's opening jaws, and this is subsequently used to calculate the maximum α.

jaw_length

The distance of the whale's jaw 'hinge' (i.e. where upper and lower jaws meet) from the rostrum, in the same units as the body_length. Can be an exact value or an allometric formula based on length. For example:

## Humpback Whale jaw location in cm (source:)
jaw_length = (10^(1.205*log10(hw_bl/100) - 0.880))*100

## Blue Whale jaw location in cm (source:)
jaw_length = 10^(1.36624*log10(bw_bl/100) - 1.21286)*100

Note the body length values (hw_bl, bw_bl) must exist externally; they cannot reference the entered body_length value internal to the function, unless this also references the same existing value.

jaw_angle_upper

This is the angle in radians off the longitudnal axis of the whale of the upper jaw at maximum gape. In both humpbacks and blue whales this is 0.5235988 (30°).

jaw_angle_lower

This is the angle in radians off the longitudnal axis of the whale of the lower jaw at maximum gape. In both humpbacks and blue whales this is 0.8726646 (50°).

a_, b_ c_, d_ inputs

a_mouth_open - when the mouth starts to open
b_max_gape_start - when maximum gape is reached
c_max_gape_end - when mouth starts to close, or how long it is held at max gape
d_mouth_closed - when mouth is completely closed

These inputs set the timings (i.e. iteration, row or frame) of these events within the model. If speed is a vector, they set the locations along the speed vector these events occur. Similarly if speed is a single value, they set similarly the timings within the model, but obviously this is related to model_length.

The complete mouth opening action does not have to occur during the model. The inputs can be used to set, for example timing of max gape to be at the last value in the speed vector. Also, if these are left NULL, the mouth will not open, and the model is equivalent to one created using attack_model.

Application of the mouth opening and morphology inputs

The function programatically determines the location of the jaw tips at each iteration of the model during the mouth opening event, and their distance from the prey, calculates their visual angle α, and combines these to give a total jaw α. This is then compared to the α of the rest of the body to determine the maximum α. These calculations are done in the vertical plane only, and occur separately from any α calculations done using the body profiles; if the total jaw α is greater than the α determined from the body widths, it will always be selected as the maximum α regardless of any filtering between vertical and horizontal planes using width_filter.