---
title: "Introduction to rosario"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to rosario}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(rosario)
```

## 1. Description of the package

The `rosario` package implements a null model analysis to quantify concurrent temporal niche overlap (i.e., activity or phenology) among biological identities (e.g., individuals, populations, or species) using the Rosario randomization algorithm (Castro-Arellano et al. 2010).

This vignette introduces the main functions and a typical workflow.

## 2. Hypothetical example dataset

The package includes an example dataset, `ex1`, with 5 biological identities across 12 time intervals. Time intervals are assumed to be circular (e.g., hours of the day, months of the year), so the last interval is treated as adjacent to the first.

Values represent counts of activity events (e.g., detections or captures) per interval.

```{r}
data("ex1")
ex1
```

The `rosario` function creates the set of cyclic shifts and their mirror images (reverse order), preserving shape while changing location along the cycle and maintaining temporal autocorrelation. The suite of vectors and mirrors represent a complete set of possible distributions.

```{r, message = FALSE}
rosario_shifts <- rosario(ex1[1,])
head(rosario_shifts)
```
 
## 3. Visualize patterns generated by `rosario()` function

Use `plot_rosario()` to visualize hypothetical time-use distributions produced by `rosario()` for a single biological identity. The function plots the first 10 hypothetical set of cyclic shifts and their mirror images. Each panel shows one hypothetical time-use distribution, with the cyclic shift in dark gray and its mirror image in dark red.

```{r, fig.width=7.5, fig.height=6}
plot_rosario(ex1[1, ], cols = 5)
```

## 4. Assemblage-wide overlap

Use `temp_overlap()` to compute the mean of all pairwise overlaps among rows (biological identities), using the chosen index: "pianka" or "czekanowski". This returns the observed assemblage-wide overlap.

This assemblage-wide summary is most informative when you have three or more biological identities (e.g., individuals, species, or communities), because it captures overall overlap rather than only pairwise comparisons.

```{r}
temp_overlap(ex1, method = "pianka")

#or

temp_overlap(ex1, method = "czekanowski")
```

## 5. Null Model Test

To test whether the observed overlap differs from random expectations, `get_null_model()` generates a null distribution of assemblage-wide overlap by repeatedly randomizing the input matrix using `rosario_sample()` and recomputing mean pairwise overlap (via `temp_overlap()`).

`get_null_model()` can run simulations in parallel by setting `parallel = TRUE` to reduce runtime on multicore machines. For CRAN checks and maximum portability, this vignette uses `parallel = FALSE`. 

We recommend using `nsim = 1000` for applied analyses, but runtime depends on hardware and dataset size.

```{r}
set.seed(1)
mod <- get_null_model(ex1, method = "pianka", nsim = 100, parallel = FALSE)
mod$p_value
```

## 6. Visualizing the null distribution

Use `temp_overlap_plot()` to compare the observed overlap (from `temp_overlap()`) against the simulated null distribution (from `get_null_model()`). The plot shows a histogram of simulated overlap values and a vertical dashed line indicating the observed overlap.

```{r}
temp_overlap_plot(mod)
```

## 7. Conclusion

This vignette demonstrates the key steps in a temporal niche overlap analysis workflow using `rosario`.

For more details on each function, see the package documentation and the examples in each function’s help page.