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

Arguments

x

numeric. Object of class constant_speed_model, variable_speed_model, or diameter_model.

response_frame

integer. The frame at which you want to determine the ALT.

new_distance

numeric. Distance in cm the specimen is from the screen, if this is different from that used to create the model.

latency

numeric. Visual response latency in seconds.

Value

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.

Details

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.

Author

Nicholas Carey - nicholascarey@gmail.com

Examples

## 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