loomeR is an R package for creating looming animations for use in behavioural and neurological experiments, and analysing escape responses, for example the Apparent Looming Threshold (ALT) of an escape (Dill 1974, Webb 1982). Looming animations are used in a range of physiological, psychological and behavioural sciences to simulate an approaching threat and investigate phenomena such as perception, visual latency, escape responses, and neurological functioning. ALT is a metric which describes the threshold where a specimen may initiate an escape movement based on a combination of the perceived distance and/or speed of an oncoming threat.

See the Reference page to view the detailed Help file for each function.

Installation

loomeR is not yet published on CRAN, but can be installed using the devtools package:

install.packages("devtools")
devtools::install_github("nicholascarey/loomeR")

Usage

Using the package is straightforward:

1. Create an animation model

The package can create simple or complex animations in three ways:

  • Use of basic inputs: enter start and end screen diameters, and total duration.
  • Use of realistic parameters: the function will determine the correct screen diameters for each animation frame using…
    • Constant speed: specify a constant speed, size, and starting distance of the hypothetical oncoming threat
    • Variable speed: provide a profile of variable speeds, plus size and starting distance of the oncoming threat

2. Create an animation from the model

To create the animation from the model, loomeR requires ffmpeg, a free, cross-platform, command-line utility for encoding video to be installed on your system. This currently works in R on macOS and Windows. Support for Linux is planned: please get in touch if you would like to help with testing on Linux systems.

Many options are available to customise the animation; specifying a frame rate, modifying the colour and background, padding the video with blank frames to a desired total duration, marking frames to assist with identifying when escape responses occur, and more.

3. Analyse escape responses

This function calculates the viewing angle, alpha (α), for each frame in the animation, and the change in this viewing angle per unit time (dα/dt in radians/second) (Dill 1974). Given a response frame the Apparent Looming Threshold (ALT, Webb 1982) can be determined. These metrics can all be corrected for different viewing distances if the specimen has moved to a different distance from the screen, which will affect the perceived α and thus ALT. The new perceived speed and distance for the different viewing distance are also returned. A visual response latency (i.e. to account for neurological lag in response time) can also be applied.

Forthcoming and potential features

  • Function to extract model parameters at a particular frame, optionally apply a latency correction, and correct the perceived speed and distance for a different viewing distance. DONE - see get_alt
  • Linux support
  • Add a receding option for animations (possibly works by setting speed as a negative, or start/end diameters the other way round, but this has not been tested)
  • Enhancements (e.g. quicker padding method) and alternative to ffmpeg
  • Option to export images only, and not convert them
  • Option to subsample or interpolate variable speed profiles to match a desired frame rate
  • Use of custom shapes (please contact me if you know of actual applications for this… it would be a lot of work)

Feedback

If you have any bugs or feedback, you can contact me via email, or by opening an issue.

Acknowledgements

Working with the following people inspired the creation of this package:

  • Paolo Domenici, CNR IAMC, Italy. Link
  • Jeremy Goldbogen & Dave Cade, Hopkins Marine Station, Stanford University. Link
  • Januar Harianto, University of Sydney Link

References

Dill, Lawrence M, 1974. The escape response of the zebra danio (Brachydanio rerio) I. The stimulus for escape. Animal Behaviour 22, 711–722. https://doi.org/10.1016/S0003-3472(74)80022-9

Webb, P.W., 1982. Avoidance responses of fathead minnow to strikes by four teleost predators. J. Comp. Physiol. 147, 371–378. https://doi.org/10.1007/BF00609671

Gibson, J. J. (2014) The Ecological Approach to Visual Perception: Classic Edition. Psychology Press. (2014).

Domenici, P. (2002). The visually mediated escape response in fish: predicting prey responsiveness and the locomotor behaviour of predators and prey. Marine and Freshwater Behaviour and Physiology, 35(1–2), 87–110. https://doi.org/10.1080/10236240290025635

Muijres, F. T., Elzinga, M. J., Melis, J. M., & Dickinson, M. H. (2014). Flies evade looming targets by executing rapid visually directed banked turns. Science, 344(6180), 172–177. https://doi.org/10.1126/science.1248955

Peron, S., & Gabbiani, F. (2009). Spike frequency adaptation mediates looming stimulus selectivity in a collision-detecting neuron. Nature Neuroscience, 12, 318. http://dx.doi.org/10.1038/nn.2259