Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Czekanowski overlap index

Description

Computes the Czekanowski index of overlap between two relative-frequency activity profiles p and q:

1 - \tfrac{1}{2}\sum_i |p_i - q_i|.

Usage

czekanowski_index(p, q)

Arguments

Details

Inputs should be on a comparable scale; if your data are raw counts, rescale rows to proportions first (see rescale_matrix()).

Value

A single numeric value in [0, 1] where 0 indicates no overlap and 1 indicates identical profiles.

Examples

set.seed(1)
n <- 6
p <- rmultinom(1, 20, rep(1, n))[,1]; p <- p / sum(p)
q <- rmultinom(1, 20, rep(1, n))[,1]; q <- q / sum(q)
czekanowski_index(p, q)

Example temporal activity dataset

Description

An example dataset of 5 biological identities across 12 time intervals. Values represent counts of activity events (e.g., detections or captures) per interval. This dataset is provided for examples and vignettes.

Usage

ex1

Format

A numeric matrix with 5 rows (biological identities) and 12 columns (time intervals):

Rows

Biological identities (bioID1 … bioID5)

Columns

Time intervals (INT1 … INT12)

Values

Counts of activity per identity × interval

Examples

ex1
rowSums(ex1)   # total activity per biological identity
colSums(ex1)   # total activity per time interval

Null-model test via ROSARIO algorithm randomization

Description

Generates a null distribution of concurrent temporal niche overlap by repeatedly randomizing the input matrix with rosario_sample() and recomputing the mean pairwise overlap (see temp_overlap()).

Usage

get_null_model(mat, method, nsim = 1000, parallel = FALSE)

Arguments

Details

For "czekanowski", rows are rescaled to proportions internally to satisfy the index's assumptions. Randomization preserves each row's temporal autocorrelation by cyclically shifting (and optionally mirroring) its profile; see rosario_sample().

When parallel = TRUE, the function calls future::plan(multisession) internally so that randomizations are distributed across available local sessions. This means the function overrides any previously set future plan. If you need custom control over parallelization (e.g. cluster backends), run the non-parallel mode (parallel = FALSE) and handle parallelism externally.

Value

A list with components:

observed_niche_overlap

Mean from all possible pairwise comparisons among biological identities for mat.

p_value

A one-sample t.test object comparing null means to the observed value (mu = observed).

null_niche_overlap

A tibble/data.frame of simulated mean overlaps (one per randomization).

See Also

temp_overlap(), rosario_sample(), temp_overlap_matrix()

Examples

get_null_model(ex1, method = "pianka", nsim = 10, parallel = FALSE)

Pianka's niche-overlap index

Description

Computes Pianka's symmetric index of overlap between two non-negative activity profiles p and q:

\frac{\sum_i p_i q_i}{\sqrt{\left(\sum_i p_i^2\right)\left(\sum_i q_i^2\right)}}.

Usage

pianka_index(p, q)

Arguments

Details

Pianka's index does not require inputs to sum to 1, but both vectors must be non-negative and not all zero.

Value

A single numeric value in [0, 1]; larger values indicate greater overlap.

Examples

set.seed(1)
n <- 10
p <- rpois(n, 3); q <- rpois(n, 3)
pianka_index(p, q)

Diagram of ROSARIO null-model randomizations

Description

Visualizes the first 10 hypothetical time use distributions produced by rosario() for a single biological identity. Each panel displays one hypothetical time use distribution with its cyclic shift shown in dark gray and its mirror image shown in dark red.

Usage

plot_rosario(numvec, normalize = TRUE, cols = 4)

Arguments

Value

Invisibly, a list with:

• variants — the original list from rosario(numvec)

• mat2k_plotted — matrix of the plotted variants (min(10, n) × 2k)

• k — number of time bins

• indices_plotted — which variant indices (1..m) were drawn

Examples

one <- c(0,5,0,7,5,13,70,0)
plot_rosario(one, cols = 4)

Row-wise rescaling of a matrix to relative frequencies

Description

Divides each row by its row sum so that every row sums to 1 (leaving dimnames intact).

Usage

rescale_matrix(m)

Arguments

Value

A numeric matrix of the same dimension with each row summing to 1. Rows with a zero sum are left unchanged (resulting in NaN if present).

Examples

ex1_rescale <- rescale_matrix(ex1)
rowSums(ex1_rescale)

Generate cyclic and mirrored permutations of a time series

Description

For a numeric vector, creates the set of cyclic shifts and their mirror images (reverse order), preserving shape but changing location along the cycle. The suite of vectors and mirrors represent a complete set of possible distributions.

Usage

rosario(numvec)

Arguments

Value

A list of numeric vectors with all the permutations in the time series, including the mirror patterns.

See Also

vec_permutation(), rosario_sample()

Examples

rosario(c(40, 25, 18, 10, 5, 2))

ROSARIO randomization of an assemblage matrix

Description

Randomly permutes each row by a uniform cyclic shift of its columns and, with probability 0.5, reverses the order (mirror image). This kind of permutations preserves each biological identity's temporal autocorrelation structure and niche breadth while randomizing location within the cycle.

Usage

rosario_sample(mat)

Arguments

Value

A numeric matrix of the same dimension as mat, randomized row-wise.

See Also

rosario(), vec_permutation()

Examples

rosario_sample(ex1)

Mean concurrent temporal niche overlap

Description

Computes the mean of all pairwise overlaps among rows (biological identities) using the chosen index.

Usage

temp_overlap(mat, method = c("pianka", "czekanowski"))

Arguments

Details

For "czekanowski", rows are automatically rescaled to proportions.

Value

A single numeric value (named by the method) equal to the mean of the lower triangle of the pairwise overlap matrix.

See Also

temp_overlap_matrix(), get_null_model()

Examples

temp_overlap(ex1, method = "pianka")
temp_overlap(rescale_matrix(ex1), method = "czekanowski")

Convert a square overlap matrix to a tidy pairwise data frame

Description

Tidies a symmetric overlap (or distance) matrix into a three-column tibble/data frame with pairs and values.

Usage

temp_overlap_df(mat)

Arguments

Value

A data frame with columns item1, item2, and distance (terminology follows stats::as.dist()).

Examples

d <- temp_overlap_matrix(ex1)
temp_overlap_df(d)

Pairwise temporal niche-overlap matrix

Description

Computes all pairwise overlaps among rows (biological identities) using the chosen index.

Usage

temp_overlap_matrix(mat, method = c("pianka", "czekanowski"))

Arguments

Details

For Czekanowski, supply a row-rescaled matrix (see rescale_matrix()) or use temp_overlap(), which handles rescaling.

Value

A square symmetric matrix of overlap values with row/colnames copied from mat. The first class of the object is set to the method name.

See Also

temp_overlap(), rescale_matrix()

Examples

temp_overlap_matrix(ex1, method = "pianka")
ex1_rescale <- rescale_matrix(ex1)
temp_overlap_matrix(ex1_rescale, method = "czekanowski")

Plot null-model results for temporal niche overlap

Description

Creates a histogram of simulated mean niche overlap values from a null model (see get_null_model()) and overlays a dashed vertical line indicating the observed mean overlap.

Usage

temp_overlap_plot(results)

Arguments

Value

A ggplot2 object displaying the null distribution of overlap values with the observed overlap marked.

See Also

get_null_model(), temp_overlap()

Examples

mod <- get_null_model(ex1, method = "pianka", nsim = 100)
temp_overlap_plot(mod)

Cyclic permutation (rotate) a numeric vector

Description

Returns a cyclic shift of numvec so that position x becomes the first element and the order wraps around the end.

Usage

vec_permutation(numvec, x = 1)

Arguments

Value

A numeric vector of the same length as numvec, rotated so that numvec[x] is first.

Examples

vec_permutation(1:6, 4)  # 4 5 6 1 2 3