Skip to contents

Randomization test for singing coordination

Source: R/test_coordination.R
test_coordination.Rd

Monte Carlo randomization test to assess the statistical significance of overlapping or alternating singing (or any other simultaneously occurring behavior).

Usage

test_coordination(
  X = NULL,
  iterations = 1000,
  ovlp.method = "count",
  randomization = "keep.gaps",
  less.than.chance = TRUE,
  parallel = 1,
  pb = TRUE,
  rm.incomp = FALSE,
  cutoff = 2,
  rm.solo = FALSE
)

Arguments

X

Data frame containing columns for singing event (sing.event), individual (indiv), and start and end time of signal (start and end).

iterations

number of iterations for shuffling and calculation of the expected number of overlaps. Default is 1000.

ovlp.method

Character string defining the method to measure the amount of overlap. Three methods are available:

  • count: count the number of overlapping signals (default)

  • time.overlap: measure the total duration (in s) in which signals overlap

  • time.closest: measure the time (in s) to the other individual's closest signal. This is the only method that can take more than 2 individuals. Note that when using this method the interpretation of the coordination score and p-values changes (see argument less.than.chance).

randomization

Character string defining the procedure for signal randomization. Three methods are available:

  • keep.gaps the position of both signals and gaps (i.e. intervals between signals) are randomized. Default.

  • sample.gaps gaps are simulated using a lognormal distribution with mean and standard deviation derived from the observed gaps. Signal position is randomized.

  • keep.song.order only the position of gaps is randomized.

More details in Masco et al. (2015).

less.than.chance

Logical. If TRUE the test evaluates whether overlaps occur less often than expected by chance. If FALSE the opposite pattern is evaluated (whether overlaps occur more often than expected by chance). Default is TRUE. Notice that the interpretation changes when using ovlp.method = "time.closest", in which case TRUE evaluates whether the time to the closest signal is shorter than expected by chance (i.e. more coordinated) and FALSE evaluates whether the time to the closest signal is longer than expected by chance (i.e. less coordinated).

parallel

Numeric. Controls whether parallel computing is applied. It specifies the number of cores to be used. Default is 1 (i.e. no parallel computing).

pb

Logical argument to control progress bar. Default is TRUE.

rm.incomp

Logical. If TRUE removes the events that don't have 2 interacting individuals. Default is FALSE.

cutoff

Numeric. Determines the minimum number of signals per individual in a singing event. Events not meeting this criterium are removed. Default is 2. Note that randomization tests are not reliable with very small sample sizes. Ideally 10 or more signals per individual should be available in each singing event.

rm.solo

Logical. Controls if signals that are not alternated at the start or end of the sequence are removed (if TRUE). For instance, the sequence of signals A-A-A-B-A-B-A-B-B-B (in which A and B represent different individuals, as in the 'indiv' column) would be subset to A-B-A-B-A-B. Default is FALSE.

Value

A data frame with the following columns:

  • sing.event: singing event ID

  • obs.overlap: observed amount of overlap (counts or total duration, depending on overlap method, see 'ovlp.method' argument)

  • mean.random.ovlp: mean amount of overlap expected by chance

  • p.value: p value

  • coor.score: coordination score (sensu Araya-Salas et al. 2017), calculated as: $$(obs.overlap - mean.random.ovlp) / mean.random.ovlp$$ Positive values indicate a tendency to overlap while negative values indicate a tendency to alternate. NA values will be returned when events cannot be randomized (e.g. too few signals).

Details

This function tests whether the temporal relationship between individuals within each singing event differs from chance expectation. For every event, a null distribution is generated by randomizing the sequences of signals and silence-between-signals according to the selected randomization procedure, repeated across the specified number of iterations. The observed value is then compared against this null distribution.

For ovlp.method = "count" and "time.overlap", the statistic represents the amount of simultaneous signaling (number or duration of overlapping signals). In this case, when less.than.chance = TRUE, the test evaluates whether overlap is lower than expected by chance (i.e., alternation), and when FALSE, whether overlap is higher than expected (i.e., greater synchrony/overlapping).

For ovlp.method = "time.closest", the statistic represents the mean temporal distance (in seconds) to the closest signal from another individual. Here, smaller values indicate tighter temporal coordination. Consequently, when less.than.chance = TRUE, the test evaluates whether individuals sing closer in time than expected by chance (i.e., stronger coordination), whereas when FALSE, it evaluates whether individuals sing farther apart than expected (i.e., weaker coordination).

The p-value corresponds to the proportion of randomized values that are as extreme as the observed value, according to the direction specified by less.than.chance.

Two coordination indices are returned: (1) an unbounded proportional deviation from the mean random expectation, and (2) a symmetric bounded index ranging from -1 to 1. For overlap-based methods, positive values indicate more overlap than expected and negative values indicate less overlap. For "time.closest", the sign is reversed in interpretation: negative values indicate shorter-than-expected distances (stronger coordination), whereas positive values indicate longer-than-expected distances (weaker coordination).

The function assumes no overlap between signals belonging to the same individual. See Masco et al. (2015) for recommendations on appropriate randomization procedures for different signal structures.

References

Araya-Salas, M., & Smith-Vidaurre, G. (2017). warbleR: An R package to streamline analysis of animal acoustic signals. Methods in Ecology and Evolution, 8(2), 184-191.

Araya-Salas M., Wojczulanis-Jakubas K., Phillips E.M., Mennill D.J., Wright T.F. (2017) To overlap or not to overlap: context-dependent coordinated singing in lekking long-billed hermits. Animal Behavior 124, 57-65.

Keenan EL, Odom KJ, M Araya-Salas, KG Horton, M Strimas-Mackey,MA Meatte, NI Mann,PJ Slater,JJ Price, and CN Templeton . 2020. Breeding season length predicts duet coordination and consistency in Neotropical wrens (Troglodytidae). Proceeding of the Royal Society B. 20202482.

Masco, C., Allesina, S., Mennill, D. J., and Pruett-Jones, S. (2015). The Song Overlap Null model Generator (SONG): a new tool for distinguishing between random and non-random song overlap. Bioacoustics.

Rivera-Caceres K, E Quiros-Guerrero E, M Araya-Salas, C Templeton & W Searcy. (2018). Early development of vocal interaction rules in a duetting songbird. Royal Society Open Science. 5, 171791.

Rivera-Caceres K, E Quiros-Guerrero, M Araya-Salas & W Searcy. (2016). Neotropical wrens learn new duet as adults. Proceedings of the Royal Society B. 285, 20161819

Author

Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr)

Examples

{
#load  simulated singing data (see data documentation)
data(sim_coor_sing)

# set global options (this can also be set within the function call)
warbleR_options(iterations = 100, pb = FALSE)

# testing if coordination happens less than expected by chance
test_coordination(sim_coor_sing)

# testing if coordination happens more than expected by chance
test_coordination(sim_coor_sing, less.than.chance = FALSE)

# using "duration" method and "keep.song.order" as randomization procedure
test_coordination(sim_coor_sing, ovlp.method =  "time.overlap",
randomization = "keep.song.order")
}
#>   sing.event obs.ovlp mean.random.ovlp p.value coor.score coor.score.bounded
#> 1     altern 1.098593         3.364736    0.00     -0.673             -0.508
#> 2       ovlp 5.991010         3.639684    1.00      0.646              0.244
#> 3    uncoord 3.097526         3.224544    0.42     -0.039             -0.020