R/get_alt.R
get_alt.Rdget_alt returns the Apparent Looming Threshold (ALT), the rate
of change of the visual angle (alpha, or a) of a looming shape
(da/dt in radians/s), at a specified frame of the animation. Typically
this is the 'response frame' - the frame at which a specimen responds to
the stimulus.
The model originally used to create the looming animation must be supplied,
along with a specified response_frame. The function returns the ALT at
this frame. It also returns the perceived speed and perceived distance of
the looming shape at this frame, as specified by the original model.
The function also allows the results to be 'corrected' in two ways:
Different viewing distance: If the observing specimen has moved, or is
otherwise at a different distance from the screen as that specified in the
original model, this will affect the perceived ALT, as well as perceived
distance and speed. To account for this, a new_distance can be specified,
and the function will correct the ALT for the new viewing distance, as well
as calculate the new perceived speed and distance.
Visual response latency: The function also allows a visual response
latency to be applied (latency, in s). Typically, there is a lag between
an animal responding (voluntarily or involuntarily) to a stimulus, and the
signal to move reaching their musculature. If this latency value is known
or has been quantified, it can be entered as latency in seconds and the
results will be returned from the closest matching frame to the
response_frame minus this duration (see Details).
get_alt(x, response_frame = NULL, new_distance = NULL, latency = 0)numeric. Object of class constant_speed_model,
variable_speed_model, or diameter_model.
integer. The frame at which you want to determine the ALT.
numeric. Distance in cm the specimen is from the screen, if this is different from that used to create the model.
numeric. Visual response latency in seconds.
The function returns a list object of class get_alt. The first
value in the output object ($alt) is the ALT in rad/s at the response
frame (with latency correction if entered). It also includes the original
looming animation model ($original_model), and an adjusted model for any
new_distance ($adjusted_model). It also returns perceived speed and
distance ($speed_perceived, $distance_perceived) at the response frame
(with latency correction) adjusted for a new viewing distance, and also the
original speed and distance in the model at that same frame without this
correction ($speed_in_model, $distance_in_model). All angular and
da/dt results are returned in radians, as is typically used in the
literature. However the output also includes these in degrees with a _deg
suffix (e.g. $alt vs. $alt_deg). All calculated (a & da/dt) and
adjusted (perceived speed and distance) parameters are available for every
frame in the $adjusted_model$model component. Note, that because
da/dt is a derivative, the da/dt vector returned in
adjusted_model$model will be one value shorter than the total number of
frames, and therefore starts with a blank value (i.e. NA). During
processing, values of da/dt are determined from the previous frame to
the current frame. Therefore a da/dt value for a particular frame is
how the angle changed from the previous frame to that frame.
Note, that since da/dt is a derivative, its value lies between
frames. The function returns the da/dt value (rate of change in the
viewing angle) between the given response_frame and the previous frame.
If, for whatever reason, you want the da/dt between the
response_frame and the next frame, simply add 1 to the response frame.
Latency: Latency is applied internally by adjusting the response frame. The
frame rate multiplied by the latency gives the number of frames 'backwards'
from the entered response_frame the function goes to extract the results.
In the event the number of frames backwards is not an integer, this is
rounded. For example, with a 60 fps animation and 0.06s latency, the
function would look to go back 3.6 frames; this is rounded to 4.
Diameter model: Note that for a diameter_model(), the ALT (i.e. da/dt
at a particular frame) can be extracted given a viewing distance, but not
a perceived distance and speed. This is because the hypothetical size of
the attacker was never specified in creating the model. While the viewing
angle (a) and its derivative (da/dt) can be calculated, the
perceived distance and/or speed cannot; a small object on screen expanding
rapidly could represent a very small object moving slowly at a close
distance, or a very large object moving rapidly at a far distance. Both of
these can produce an identical da/dt, but without a size being
specified the speed and distance cannot be determined. Of course,
expressing the ALT as a da/dt value is designed to negate this exact
issue, by focussing purely on the rate of change of the viewing angle. If
these perceived speed and distance parameters may be important to your
study however, the model should be created in constant_speed_model() or
variable_speed_model(). Note, diameter_model() is intended to produce
simple animations purely to induce a response where the precise parameters
are not that important.
## create looming animation model
loom_model <- constant_speed_model(
screen_distance = 20,
frame_rate = 60,
speed = 500,
attacker_diameter = 50,
start_distance = 1000)
## Extract the ALT at frame 100
get_alt(loom_model,
response_frame = 100)
#>
#> Extraction complete.
#>
#> Response Frame: 100
#> Response Frame Adjusted: 100
#> Latency Applied: 0s
#>
#> The Apparent Looming Threshold is:
#> ALT: 0.8517 radians/sec
## Adjust for different viewing distance and apply a response latency
get_alt(loom_model,
response_frame = 100,
new_distance = 25,
latency = 0.06)
#>
#> Extraction complete.
#>
#> Response Frame: 100
#> Response Frame Adjusted: 96
#> Latency Applied: 0.06s
#> New Screen Distance: 25cm
#> The Apparent Looming Threshold is:
#> ALT: 0.4754 radians/sec