README.md

CRAN_Status_Badge Travis build
status AppVeyor build
status Coverage
status license DOI HitCount

Welcome

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

diameter_model(), constant_speed_model(), variable_speed_model()

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

2. Create an animation from the model

looming_animation()

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

get_alt()

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.

Example code

The included documentation is comprehensive, and a vignette explaining how to use the package is in preparation. For a quick evaluation try out the following code:

1. Create a model
library(loomeR) # load the package

# Simple constant speed model
# (speed in cm/s, frame rate in Hz, all other inputs in cm)

x <- constant_speed_model(
  screen_distance = 20,    # How far from the screen is your observing specimen?
  frame_rate = 60,         # Frame rate you want the final animation to be 
  speed = 500,             # Speed of the simulated oncoming object
  attacker_diameter = 50,  # Diameter of the simulated oncoming object
  start_distance = 1000)   # Starting distance of the simulated oncoming object
2. Use the model to create the animation
looming_animation(x)
3. Extract the ALT
# E.g. from response frame 100, and applying a response latency of 60 milliseconds
get_alt(x, response_frame = 100, latency = 0.06)
#> 
#> Extraction complete. 
#>  
#> Response Frame:            100
#> Response Frame Adjusted:   96
#> Latency Applied:           0.06s
#>  
#> The Apparent Looming Threshold is: 
#> ALT: 0.5911 radians/sec

Forthcoming and potential features

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:

Cite

If you use loomeR in your work, a citation using this zenodo DOI would be much appreciated:

DOI

Or run this code:

citation("loomeR")
#> 
#> To cite package 'loomeR' in publications use:
#> 
#>   Nicholas Carey (2019). loomeR: Looming Animations for Use in
#>   Behavioural and Neurological Experiments.
#>   https://github.com/nicholascarey/loomeR,
#>   https://doi.org/10.5281/zenodo.1212570.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {loomeR: Looming Animations for Use in Behavioural and Neurological Experiments},
#>     author = {Nicholas Carey},
#>     year = {2019},
#>     note = {https://github.com/nicholascarey/loomeR, https://doi.org/10.5281/zenodo.1212570},
#>   }
#> 
#> ATTENTION: This citation information has been auto-generated from
#> the package DESCRIPTION file and may need manual editing, see
#> 'help("citation")'.

If you don’t have the space to cite it, not a problem, but please do let me know if you use it in your experiments. I would love to keep an updated list of studies which have made use of it, and I can help publicise your paper by tweeting about it!

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



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