get_alt: Determine the Apparent Looming Threshold (ALT) for a given...

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/get_alt.R


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:


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.


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.


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.


Nicholas Carey - [email protected]

See Also

constant_speed_model(), variable_speed_model(), diameter_model(), looming_animation()


## 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
        response_frame = 100)

## Adjust for different viewing distance and apply a response latency
        response_frame = 100,
        new_distance = 25,
        latency = 0.06)

nicholascarey/loomeR documentation built on July 15, 2019, 7:54 a.m.