attack_model_whale: Attack Model
In nicholascarey/attackR: Models an Attack by a Predator on a Prey

Description Usage Arguments Details jaw_length jaw_angle_upper jaw_angle_lower a_, b_ c_, d_ inputs Application of the mouth opening and morphology inputs Author(s)

View 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)

`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.

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 α.

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.

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°).

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_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.

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.

Nicholas Carey - nicholascarey@gmail.com, Dave Cade davecade@stanford.edu,

nicholascarey/attackR documentation built on July 22, 2020, 11:41 p.m.