Rosario R package tests temporal overlap in British Columbia cervids

The Rosario randomisation algorithm is now available as an R package, providing researchers with a null-model test of whether cyclical activity patterns shared by multiple organisms differ from patterns expected under a time-preserving randomisation scheme. The R implementation expands access to a method originally developed for analysing diel temporal overlap within local ecological communities. In a demonstration using camera-trap records from British Columbia, Canada, researchers applied the package to the daily schedules of mule deer, elk and white-tailed deer, evaluating their concurrent overlap as well as individual pairwise overlap values.

Ecological time has a structure that ordinary randomisation can obscure. Habitat, food and time are major dimensions of a species’ niche, and access to resources during particular parts of the daily cycle may influence survival. Species can partition resources spatially or trophically, as well as through differences in the timing of resource use. Daily activity, tidal patterns and annual phenology are cyclical because observations repeat around a closed sequence: the end connects back to the beginning. Adjacent time intervals in these observations are temporally dependent, so treating them as unrelated categories can erase the autocorrelation that gives cyclical patterns their shape.

Rosario was designed specifically for data with this circular structure. Its null model generates alternative arrangements by shifting entire empirical time-use patterns around the cycle and adding mirror images of those shifts. Each alternative retains the original frequency distribution and temporal autocorrelation but changes the location of the pattern within the full time extent. This approach differs from the scrambled-zeros and conserved-zeros randomisation models, which were developed for non-sequential resource matrices in which resource categories are unordered. Those models treat zero values differently and disrupt the circular structure of cyclical observations.

The rosario() function performs the initial randomisation step. It advances an observed pattern sequentially until its modal value has occupied each interval in the complete time extent, producing a set of cyclic shifts. It also constructs mirror images by reversing the order of each pattern. For an analysis involving several biological identities, the package randomly selects one shifted or mirrored scenario for each identity and combines those choices into a pseudo-observation matrix. It then calculates the mean of all pairwise overlaps in that matrix and repeats the operation to generate a null frequency distribution, commonly through about 1,000 simulations.

Two indices are available for quantifying similarity in resource use, here interpreted as time use: Pianka’s overlap index and the Czekanowski index. The observed value can be compared with the simulated distribution to evaluate concurrent overlap among all included identities. This is the principal analytical distinction between Rosario and tools centred on pairwise comparison. Pairwise estimates can characterise similarity between two organisms, but aggregating those estimates does not directly test the overlap exhibited simultaneously by an entire assemblage. Rosario’s null model evaluates that shared pattern within one analysis involving three or more biological identities.

The R package provides functions for the main stages of this workflow. The temp_overlap() function calculates observed mean pairwise overlap using the selected index, and get_null_model() performs the randomisation test. Plotting tools show the first ten hypothetical time-use distributions for a selected identity and display the simulated overlap frequencies alongside the observed value. Input takes the form of a matrix, with rows representing individuals, species or populations and columns representing time intervals. Researchers can also use rescale_matrix() to convert rows to proportions, which can be useful when comparisons involve entities with very different sample sizes. The stable release is available through CRAN, with a development repository and a real-world vignette hosted on GitHub.

The demonstration drew on summer observations from the SIM Deer project in British Columbia, obtained through the publicly accessible Wildlife Insights platform. The analysis covered June, July and August in 2020, 2021 and 2022 and included 85,929 capture events: 51,691 involving mule deer, 19,395 involving elk and 14,843 involving white-tailed deer. Capture records were assigned to 30-minute intervals, with the interval width chosen before analysis according to the study objectives and the need for biologically meaningful comparisons. The input matrix contained one row for each of the three cervid species and one column for each interval in the 24-hour cycle.

The resulting activity curves suggested that the species shared some timing while varying in their daily distributions. Mule deer showed peaks around dawn, at approximately 06:00, and dusk, at approximately 18:00, with additional activity during nighttime hours. Elk displayed a strong peak around dusk, a substantial daytime peak around 10:00 to 11:00 and some nocturnal activity. White-tailed deer also showed dawn and dusk peaks, although its dusk peak was less pronounced than that of mule deer, and it exhibited noticeable activity around midday. Taken together, the curves were consistent with a degree of crepuscular behaviour across the three species. Their visible similarities and variations, however, cannot by themselves establish whether concurrent overlap is unusual; that question is addressed by comparing the observed value with the cyclic null distribution.

Calculations from Rosario, the activity package and the overlap package produced broadly similar overlap values, indicating that Rosario’s Pianka and Czekanowski indices yielded results comparable to those obtained with the other R approaches. The analytical scope nevertheless differed. The activity and overlap tools chiefly supplied statistical comparisons between species pairs, whereas Rosario additionally returned pairwise indices and a null-model assessment of overlap among all three cervids. The example therefore combines two kinds of output: a numerical description of activity and overlap and an evaluation of the combined pattern against an alternative distribution generated while preserving the circular structure of the observations.

Several limitations constrain how the method should be applied. Rosario is designed for cyclical rather than sequential data. Sequential observations have a genuine beginning and end and do not possess the same circular structure, although long-term camera-trap records can be mapped onto a cyclical domain such as time of day, season or year before analysis. Comparisons among organisms that are not sympatric require additional care because differences in yearly variation can affect activity or phenology. For diel data, time transformation may be required depending on a study’s location, duration and latitudinal separation among sampling sites. These constraints make temporal alignment and explicit ecological assumptions essential, while the move to R broadens access to the algorithm and supports more standardised comparison with existing packages for activity, overlap and cyclical ecological data.

Subject of Research: Null-model analysis of concurrent temporal niche overlap in cyclical ecological data

Article Title: Rosario: An algorithm to analyse cyclical data in Ecology

Article References: Velásquez-Roa, T., Hurtado-Materon, M., Robles-Fernández, A., & Castro-Arellano, I. (2026). Rosario: An algorithm to analyse cyclical data in Ecology. Biodiversity Data Journal, 14, Article e176358. https://doi.org/10.3897/bdj.14.e176358

Image Credits: AI Generated

DOI: 10.3897/BDJ.14.e176358

Keywords: Rosario algorithm, R package, temporal niche overlap, null models, cyclic randomisation, camera traps, cervid activity, Pianka overlap, Czekanowski overlap, ecological time series, Rosario, algorithm