# rotation_test

Carry out a rotation randomization test

## Syntax

#### Matlab & Octave

result = rotation_test(event_times, full_period, exp_period, n_rot, ts_fun, skip_sort, conf_level, return_rot_stats, varargin)

#### R

result <- rotation_test(event_times, exp_period, full_period = range(event_times, na.rm=TRUE), n_rot=10000, ts_fun=length, skip_sort=FALSE, conf_level=0.95, return_rot_stats=FALSE, ...)

## Description

Carry out a rotation test (as applied in Miller et al. 2004 and detailed in DeRuiter and Solow 2008). This test is a variation on standard randomization or permutation tests that is appropriate for time-series of non-independent events (for example, time series of behavioral events that tend to occur in clusters). This implementation of the rotation test compares a test statistic (some summary of an “experimental” time-period) to its expected value during non-experimental periods. Instead of resampling random subsets of observations from the original dataset, the rotation test samples many contiguous blocks from the original data, each the same duration as the experimental period. The summary statistic, computed for these “rotated” samples, provides a distribution to which the test statistic from the data can be compared.

## Inputs

Input var | Description | Units | Defualt |
---|---|---|---|

event_times | is a vector of the times of events. Times can be given in any format. If event_times should not be sorted prior to analysis (for example, if times are given in hours of the day and the times in the dataset span several days), be sure to specify skip_sort=true. | N/A | N/A |

full_period | is a length two vector giving the start and end times of the full period during which events in event_times might have occurred. If missing, default is [min(event_times), max(event_times)]. | N/A | [min(event_times), max(event_times)] |

exp_period | A two-column vector, matrix, or data frame specifying the start and end times of the “experimental” period for the test. If a matrix or data frame is provided, one column should be start time(s) and the other end time(s). Note that all data that falls into any experimental period will be concatenated and passed to ts_fun. If finer control is desired, consider writing your own test using the underlying function rotate. | N/A | N/A |

n_rot | the number of rotations (randomizations) to carry out. Default is n_rot=10000. | N/A | 10000 |

ts_fun | is a function to compute the test statistic. Input provided to this function will be the times of events that occur during the “experimental” period. The default function is length - in other words, the default test statistics is the number of events that happen during the experimental period. | N/A | length |

skip_sort | is a Logical statement. Should times be sorted in ascending order? Default is skip_sort=false. | logical | false |

conf_level | is the confidence level to be used for the bootstrap CI calculation, specified as a proportion. conf_level=0.95, or 95% confidence. | N/A | .95 |

return_rot_stats | is a Logical statement. Should output include the test statistics computed for each rotation of the data? Default is return_rot_stats=false. | logical | false |

varargin/… | is additional inputs to be passed to ts_fun | N/A | N/A |

## Outputs

Output var | Description | Units |
---|---|---|

statistic | Test statistic (from original data) | N/A |

p_value | P-value of the test (2-sided) | N/A |

n_rot | Number of rotations | N/A |

CI_low | Lower bound on rotation-resampling percentile-based confidence interval | N/A |

CI_up | Upper bound on rotation-resampling percentile-based confidence interval | N/A |

conf_level | Confidence level, as a proportion | % |

rot_stats | If return_rot_stats = true, a vector of n_rot statistics from the rotated datasets is also returned. | N/A |

## References

Miller, P. J. O., Shapiro, A. D., Tyack, P. L. and Solow, A. R. (2004). Call-type matching in vocal exchanges of free-ranging resident killer whales, Orcinus orca. Anim. Behav. 67, 1099–1107.

DeRuiter, S. L. and Solow, A. R. (2008). A rotation test for behavioural point-process data. Anim. Behav. 76, 1103–1452.

## Notes & assumptions

- Note: Advanced users seeking more flexibility may want to use the underlying function rotate to carry out customized rotation resampling. rotate generates one rotated dataset from event_times and exp_period.
- Output sampling rate is the same as the input sampling rate.
- Frame: This function assumes a [north,east,up] navigation frame and a [forward,right,up] local frame. In these frames, a positive pitch angle is an anti-clockwise rotation around the y-axis. A positive roll angle is a clockwise rotation around the x-axis. A descending animal will have a negative pitch angle while an animal rolled with its right side up will have a positive roll angle.
- This function output can be quite sensitive to the inputs used, namely those that define the relative weight given to the existing data, in particular regarding (x,y)=(lat,long); increasing q3p, the (x,y) state variance, will increase the weight given to independent observations of (x,y), say from GPS readings.

## Example

### Matlab & Octave

r <- rotation_test((20*rand(500,1)), [], [10,200], [],'mean', [], [], true)

### R

r <- rotation_test(event_times = 2000*runif(500), exp_period = c(100,200), return_rot_stats=TRUE, ts_fun=mean)

## About

bugs@animaltags.org Last modified: 8 August 2017