| Title: | Ready-to-Analyze Datasets from Camera Trap Data |
| Version: | 0.1.0 |
| Description: | Functions to build datasets ready for statistical analysis from camera trap data: GLMM/GAMM on counts/RAI at various temporal levels, group size, occupancy, kernel/circular analysis of activity patterns, temporal interactions between species, hierarchical diel models, and classic capture-mark-recapture. Input data must be formatted in the style produced by 'camtrapR', the standard convention in the field. |
| License: | GPL (≥ 3) |
| Encoding: | UTF-8 |
| Depends: | R (≥ 4.1.0) |
| Imports: | dplyr, lubridate, tidyr |
| Config/roxygen2/version: | 8.1.0 |
| Suggests: | camtrapR, GLMMadaptive, knitr, rmarkdown, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| LazyData: | true |
| URL: | https://github.com/OrlandoTomassini/soReta |
| BugReports: | https://github.com/OrlandoTomassini/soReta/issues |
| NeedsCompilation: | no |
| Packaged: | 2026-09-03 09:47:18 UTC; orlan |
| Author: | Orlando Tomassini |
| Maintainer: | Orlando Tomassini <orlando.tomassini@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-09-12 14:10:03 UTC |
Convert an individual x occasion table (or a list per species) into CMR capture-history strings
Description
Convert an individual x occasion table (or a list per species) into CMR capture-history strings
Usage
as_capture_strings(ch, na_symbol = ".")
Arguments
ch |
a data.frame produced by build_cmr_day()/build_cmr_block() (Individual column + occasion columns), OR the whole list (one element per species) if you have not disabled speciesCol upstream. |
na_symbol |
symbol to use for missing occasions (NA). Default "." (MARK/RMark convention). |
Value
if ch is a data.frame: a character vector with names = Individual, values = capture-history string (e.g. "1.010"). If ch is a list: a named list per species, same structure per element.
Build an N-day-block individual x block capture history (classic CMR)
Description
Build an N-day-block individual x block capture history (classic CMR)
Usage
build_cmr_block(
recordTable,
camOp,
block_days,
individualCol = "Individual",
speciesCol = "Species",
stationCol = "Station",
dateTimeCol = "DateTimeOriginal",
min_days = 1
)
Arguments
recordTable |
data.frame produced by camtrapR::recordTableIndividual(). |
camOp |
effort matrix produced by cameraOperation(). |
block_days |
block length in days (positive integer). |
individualCol |
name of the individual ID column (default "Individual"). |
speciesCol |
name of the species column (default "Species"). If present in recordTable, the result is split by species into a named list. Pass NULL to disable this (a single data.frame). |
stationCol |
name of the station column (default "Station"). |
dateTimeCol |
name of the date/time column (default "DateTimeOriginal"). |
min_days |
minimum number of overall active station-days in the block (summed across all stations) for it to be treated as a genuine 0 rather than NA (default 1). Only a lower-bound check (>= 0) is enforced: unlike build_site_block()'s per-station min_days, this one is a total across however many stations camOp contains, so no single fixed upper bound applies universally. |
Value
If speciesCol is present: named list, one data.frame per species. Otherwise: a single data.frame. Each data.frame has an Individual column and one column per block of the period covered by camOp ("YYYY-MM-DD–YYYY-MM-DD"), values 0/1/NA as described above.
Build a daily individual x day capture history (classic CMR)
Description
Build a daily individual x day capture history (classic CMR)
Usage
build_cmr_day(
recordTable,
camOp,
individualCol = "Individual",
speciesCol = "Species",
stationCol = "Station",
dateTimeCol = "DateTimeOriginal"
)
Arguments
recordTable |
data.frame produced by camtrapR::recordTableIndividual(). |
camOp |
effort matrix produced by cameraOperation(). |
individualCol |
name of the individual ID column (default "Individual"). |
speciesCol |
name of the species column (default "Species"). If present in recordTable, the result is split by species into a named list. Pass NULL to disable this (a single data.frame). |
stationCol |
name of the station column (default "Station"). |
dateTimeCol |
name of the date/time column (default "DateTimeOriginal"). |
Value
If speciesCol is present: named list, one data.frame per
species (result[["SpeciesName"]]). Otherwise: a single data.frame.
Each data.frame has an Individual column and one column per truly
active day covered by camOp ("YYYY-MM-DD"), values 0/1 only (see
Details – no NA case at this daily grain).
Build a dataset with 1 row per calendar day, aggregating across all stations
Description
Build a dataset with 1 row per calendar day, aggregating across all stations
Usage
build_day_total(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Date, n_stations_active (number of
stations active that day), N_sp (number of species detected that
day, across all stations), and for each species two columns:
"<species>_N" (sum of independent events across all stations active
that day) and "<species>_RAI" (= N / n_stations_active * 100,
rounded to 2 decimals).
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a binomial site x N-day-block x time-bin x species dataset
Description
Build a binomial site x N-day-block x time-bin x species dataset
Usage
build_diel_binomial_block(
recordTable,
camOp,
block_days,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
bin_hours = 1,
min_days = NULL
)
Arguments
recordTable |
camtrapR-style data.frame. |
camOp |
effort matrix produced by cameraOperation(). |
block_days |
block length in days (positive integer). |
stationCol, speciesCol, dateTimeCol |
names of the relevant columns. |
bin_hours |
time-bin width, in hours (default 1). |
min_days |
if specified (0 to block_days), keeps only site x block with n_days_active >= min_days. Default NULL. |
Value
data.frame with Station, block_start, block_end, n_days_active, Time, Species, success, failure, Site_Block.
Build a binomial site x month x time-bin x species dataset
Description
Build a binomial site x month x time-bin x species dataset
Usage
build_diel_binomial_month(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
bin_hours = 1,
min_days = NULL
)
Arguments
recordTable |
camtrapR-style data.frame. |
camOp |
effort matrix produced by cameraOperation(). |
stationCol, speciesCol, dateTimeCol |
names of the relevant columns. |
bin_hours |
time-bin width, in hours (default 1). |
min_days |
if specified (0 to 31), keeps only site x month with n_days_active >= min_days. Default NULL. |
Value
data.frame with Station, sampling_event ("YYYY-MM"), n_days_active, Time, Species, success, failure, Site_Event.
Build a binomial site x period/season x time-bin x species dataset
Description
Build a binomial site x period/season x time-bin x species dataset
Usage
build_diel_binomial_period(
recordTable,
camOp,
period_names,
period_starts,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
bin_hours = 1,
min_days = NULL
)
Arguments
recordTable |
camtrapR-style data.frame. |
camOp |
effort matrix produced by cameraOperation(). |
period_names |
vector of period labels, e.g. c("winter","spring","summer","autumn"). |
period_starts |
vector of "DD/MM/YYYY" dates, same length as period_names – start of each period, recurring every year. |
stationCol, speciesCol, dateTimeCol |
names of the relevant columns. |
bin_hours |
time-bin width, in hours (default 1). |
min_days |
if specified, keeps only site x period with n_days_active >= min_days. Default NULL. Only a lower-bound check (>= 0) is enforced: unlike the monthly version's fixed 31-day ceiling, a period's length is entirely user-defined. |
Value
data.frame with Station, period_name, year, period_start ("DD/MM"), period_end ("DD/MM"), n_days_active, Time, Species, success, failure, Site_Period.
Build a non-aggregated, day-by-day site x day x time-bin x species dataset
Description
Build a non-aggregated, day-by-day site x day x time-bin x species dataset
Usage
build_diel_day(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
bin_hours = 1,
tz = "UTC"
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
stationCol |
name of the station column (default "Station"). |
speciesCol |
name of the species column (default "Species"). |
dateTimeCol |
name of the date/time column (default "DateTimeOriginal"). |
bin_hours |
time-bin width, in hours (default 1). Must divide 24 exactly (e.g. 1, 2, 3, 4, 6, 0.5, 0.25). |
tz |
time zone of the stations, used to build the "date" column (default "UTC"). |
Value
data.frame with columns Station, Date (Date class, real day, always a truly active day for that station), date (POSIXct class, local noon of Date in the tz time zone. Time (start of the time bin, 0-24), Species, detected (0/1).
Build a dataset with 1 row per calendar day, with group size statistics across all stations
Description
Build a dataset with 1 row per calendar day, with group size statistics across all stations
Usage
build_group_day_total(
recordTable,
camOp,
countCol,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Date, n_stations_active (number of
stations active that day), N_sp (number of species detected that
day, across all stations), and for each species four columns:
"<species>_mean_group_size", "<species>_max_group_size",
"<species>_sum_group_size", "<species>_RAI_individuals" (=
sum_group_size / n_stations_active * 100, rounded to 2 decimals).
NA (not 0) if the species had no events, at any station, that day.
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a site x N-day-block dataset with group size statistics per species
Description
Build a site x N-day-block dataset with group size statistics per species
Usage
build_group_size_block(
recordTable,
camOp,
countCol,
block_days,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
min_days = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
block_days |
block length in days (positive integer). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
min_days |
if specified (0 to block_days), keeps only rows with n_days_active >= min_days. Default NULL = no filter. |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, block_start, block_end,
n_days_active, N_sp (number of species with at least one event in
the block), and for each species four columns:
"<species>_mean_group_size", "<species>_max_group_size",
"<species>_sum_group_size", and "<species>_RAI_individuals" (=
sum_group_size / n_days_active * 100, rounded to 2 decimals). NA
(not 0) if the species had no events in that block.
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a site x day dataset with group size statistics per species
Description
Build a site x day dataset with group size statistics per species
Usage
build_group_size_day(
recordTable,
camOp,
countCol,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, Date, N_sp (number of species
with at least one event that day), and for each species present in
recordTable three columns: "<species>_mean_group_size",
"<species>_max_group_size", "<species>_sum_group_size" – computed
across that species' independent events on that day. NA (not 0) if
the species had no events that day. Includes only the days on which
the station was active in camOp.
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a dataset with 1 row per independent event, including group size
Description
Build a dataset with 1 row per independent event, including group size
Usage
build_group_size_events(
recordTable,
camOp,
countCol,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, Species, DateTime (start of the event's bout), Date (the calendar day of DateTime), Time ("HH:MM:SS", the time of day of DateTime), group_size (the MAXIMUM value of countCol across all photos in that bout – never the sum, to avoid double-counting the same individuals photographed more than once within one passage). Includes only events that fell on a truly active day for that station.
Build a site x month dataset with group size statistics per species
Description
Build a site x month dataset with group size statistics per species
Usage
build_group_size_month(
recordTable,
camOp,
countCol,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
min_days = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
min_days |
if specified (0 to 31), keeps only rows with n_days_active greater than or equal to min_days. Default NULL = no filter. NB: the possible maximum varies month by month (see the n_days_in_month column) – 31 is only the theoretical upper bound. |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, year, month, month_start,
month_end, n_days_active, n_days_in_month, N_sp (number of species
with at least one event that month), and for each species four
columns: "<species>_mean_group_size", "<species>_max_group_size",
"<species>_sum_group_size", "<species>_RAI_individuals" (=
sum_group_size / n_days_active * 100, rounded to 2 decimals). NA
(not 0) if the species had no events that month.
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a site x period/season dataset with group size statistics per species
Description
Build a site x period/season dataset with group size statistics per species
Usage
build_group_size_period(
recordTable,
camOp,
countCol,
period_names,
period_starts,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
period_names |
vector of period labels, e.g. c("winter","spring","summer","autumn"). |
period_starts |
vector of "DD/MM/YYYY" dates, same length as period_names – the start date of each period, recurring every year. |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, period_name, year,
period_start ("DD/MM", no year), period_end ("DD/MM", no year),
period_length_days, n_days_active, N_sp (number of species with at
least one event in that period), and for each species four columns:
"<species>_mean_group_size", "<species>_max_group_size",
"<species>_sum_group_size", "<species>_RAI_individuals" (=
sum_group_size / n_days_active * 100, rounded to 2 decimals). NA
(not 0) if the species had no events in that period.
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a dataset with 1 row per site, with group size statistics over the entire activity period
Description
Build a dataset with 1 row per site, with group size statistics over the entire activity period
Usage
build_group_size_total(
recordTable,
camOp,
countCol,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
countCol |
name of the column in recordTable holding the number of animals per photo (e.g. "N_individuals"). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, n_days_active, N_sp (number
of species with at least one event over the entire period), and for
each species four columns: "<species>_mean_group_size",
"<species>_max_group_size", "<species>_sum_group_size",
"<species>_RAI_individuals" (= sum_group_size / n_days_active * 100,
rounded to 2 decimals). NA (not 0) if the species was never
detected at that station.
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build, for each species, a site x N-day-block detection history
Description
Build, for each species, a site x N-day-block detection history
Usage
build_occupancy_block(
recordTable,
camOp,
block_days,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
min_days = 1
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
block_days |
block length in days (positive integer). 1 = daily (equivalent to build_occupancy_day), 7 = weekly, etc. |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
min_days |
minimum number of active days in the block for it to be treated as a genuine 0 rather than NA (default 1). |
Value
named list, one data.frame per species. Each data.frame has a Station column and one column per block of the period covered by camOp (column name = "YYYY-MM-DD–YYYY-MM-DD", block start and end), values 0/1/NA as described above.
Build, for each species, a daily site x day detection history
Description
Build, for each species, a daily site x day detection history
Usage
build_occupancy_day(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal"
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
Value
named list, one data.frame per species. Each data.frame has a Station column and one column per day of the period covered by camOp (column name = date "YYYY-MM-DD"), values 0/1/NA as described above.
Build a site x N-day-block dataset with independent-event counts per species
Description
Build a site x N-day-block dataset with independent-event counts per species
Usage
build_site_block(
recordTable,
camOp,
block_days,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
min_days = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
block_days |
block length in days (positive integer). 1 = daily, 7 = weekly, 8, 30, etc. |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
min_days |
if specified (0 to block_days), keeps only rows with n_days_active >= min_days. Default NULL = no filter. |
independence_method |
how consecutive photos of the same species
are collapsed into one independent event: "chain" (default, compares each photo to the previous one) or
"window" (compares each photo to the start of the current bout; a
bout can never last longer than threshold_min). See
|
require_uninterrupted |
if TRUE, applies O'Brien et al. (2003)'s third independence criterion: two photos of the same species are only subject to the time threshold if no photo of ANY other species falls chronologically between them at that station; otherwise they are always independent. Default FALSE (matches every verified implementation checked in the literature). |
Value
data.frame with columns Station, block_start, block_end, mid_day
(day halfway between block_start and block_end, handy for joining
external daily covariates), n_days_active, N_sp (number of species
with at least one event in the block), and for each species present
in recordTable two columns: "<species>_N" (independent-event count)
and "<species>_RAI" (Relative Abundance Index = count /
n_days_active * 100, rounded to 2 decimals).
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a site x day dataset with independent-event counts per species
Description
Build a site x day dataset with independent-event counts per species
Usage
build_site_day(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, Date, N_sp (number of species
with at least one event that day), and one "<species>_N" column
(independent-event count) per species present in recordTable. No
"<species>_RAI" columns (redundant at the daily level – see above).
Includes only the days on which the station was active in camOp.
Build a site x month dataset with independent-event counts per species
Description
Build a site x month dataset with independent-event counts per species
Usage
build_site_month(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
min_days = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
min_days |
if specified (0 to 31), keeps only rows with n_days_active greater than or equal to min_days. Default NULL = no filter. NB: the possible maximum varies month by month (see the n_days_in_month column) – 31 is only the theoretical upper bound. |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, year, month, month_start, month_end,
mid_day (day halfway between month_start and month_end, handy for a
join with external daily covariates), n_days_active,
n_days_in_month, N_sp (number of species with at least one event in
the month), and for each species two columns: "<species>_N"
(independent-event count) and "<species>_RAI" (Relative Abundance
Index = count / n_days_active * 100, rounded to 2 decimals).
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a site x period/season dataset with independent-event counts per species
Description
Build a site x period/season dataset with independent-event counts per species
Usage
build_site_period(
recordTable,
camOp,
period_names,
period_starts,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
min_days = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
period_names |
vector of period labels, e.g. c("winter","spring","summer","autumn"). Also defines the number of groups (here: 4). |
period_starts |
vector of "DD/MM/YYYY" dates, same length as period_names, same order – the start date of each period. The day-month pattern repeats every year; the year written is only a reference used to build the date. |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
min_days |
if specified, keeps only rows with n_days_active greater than or equal to min_days. Default NULL = no filter. Only a lower-bound check (min_days >= 0) is enforced here: unlike build_site_month()'s fixed 31-day ceiling, a period's maximum length is entirely user-defined (see the period_length_days column), so no universal upper bound exists to validate against. |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, period_name, year, period_start
("DD/MM", no year), period_end ("DD/MM", no year), mid_day (a REAL
Date, with year – the day halfway between the start and end of the
period, handy for a join with external daily covariates),
period_length_days, n_days_active, N_sp (number of species with at
least one event in the period), and for each species two columns:
"<species>_N" (independent-event count) and "<species>_RAI"
(Relative Abundance Index = count / n_days_active * 100, rounded to
2 decimals).
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Build a dataset with 1 row per site, aggregating over the entire activity period
Description
Build a dataset with 1 row per site, aggregating over the entire activity period
Usage
build_site_total(
recordTable,
camOp,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation(). |
stationCol |
name of the station column in recordTable (default "Station"). |
speciesCol |
name of the species column in recordTable (default "Species"). |
dateTimeCol |
name of the date/time column in recordTable (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
data.frame with columns Station, n_days_active (total active
days over the entire period), N_sp (number of species with at least
one event over the entire period), and for each species two columns:
"<species>_N" (independent-event count over the entire period) and
"<species>_RAI" (= N / n_days_active * 100, rounded to 2 decimals).
Note
Species names in the columns are cleaned (spaces and non-alphanumeric characters replaced by "_") via the internal .sanitize_species_names().
Compute the AA/ABA and BB/BAB intervals between two species (Parsons et al. 2016, T3/T4)
Description
Compute the AA/ABA and BB/BAB intervals between two species (Parsons et al. 2016, T3/T4)
Usage
build_species_pair_interruptions(
recordTable,
speciesA,
speciesB,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
speciesA, speciesB |
names of the two species to compare (as they appear in speciesCol). |
stationCol |
name of the station column (default "Station"). |
speciesCol |
name of the species column (default "Species"). |
dateTimeCol |
name of the date/time column (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
long data.frame with columns Station, type ("AA", "ABA", "BB"
or "BAB"), time_from (start of the interval) and delta_hours
(duration). For the T4/T3 comparison of Parsons et al., extract the
vectors with:
AA <- out$delta_hours[out$type == "AA"]
ABA <- out$delta_hours[out$type == "ABA"]
(and likewise for BB/BAB).
Compute the AB/BA intervals between two species (Niedballa et al. 2019 method), with censoring
Description
Compute the AB/BA intervals between two species (Niedballa et al. 2019 method), with censoring
Usage
build_species_pair_intervals(
recordTable,
camOp,
speciesA,
speciesB,
stationCol = "Station",
speciesCol = "Species",
dateTimeCol = "DateTimeOriginal",
threshold_min = 30,
max_gap_hours = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
camOp |
effort matrix produced by cameraOperation() – used to determine the end of each station's monitoring period, for censoring intervals with no subsequent event. |
speciesA, speciesB |
names of the two species to compare (as they appear in speciesCol). |
stationCol |
name of the station column (default "Station"). |
speciesCol |
name of the species column (default "Species"). |
dateTimeCol |
name of the date/time column (default "DateTimeOriginal"). |
threshold_min |
independence threshold in minutes (default 30). |
max_gap_hours |
if specified, truncates (administrative censoring) intervals longer than this number of hours: delta_hours is capped at max_gap_hours and censored becomes TRUE. Does not discard rows. Default NULL = no truncation. |
independence_method |
how consecutive photos of the same species are collapsed into one independent event: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE). See build_site_block() docs. |
Value
long data.frame with columns Station, direction ("AB" or "BA"),
time_from (timestamp of the starting event), delta_hours (hours until
the next event of the other species, or until the censoring limit)
and censored (TRUE if there was no subsequent event before the limit
– end of monitoring or max_gap_hours). For the Niedballa comparison,
extract the two vectors with:
AB <- out$delta_hours[out$direction == "AB"]
BA <- out$delta_hours[out$direction == "BA"]
(and decide yourself whether to include or exclude rows with censored == TRUE).
Example camera effort matrix for soReta
Description
A station x day effort matrix, built once from
camtraps_soReta via camtrapR::cameraOperation(),
and bundled directly with the package: using soReta's example
data no longer requires camtrapR at all, since this object is
already the finished result of that step. Any station x day matrix
in this shape works equally well with every function in this
package; cameraOperation() is simply the standard, convenient
way to build one from deployment/retrieval/malfunction dates – you
are not required to use camtrapR to build your own.
Usage
camOp_soReta
Format
A matrix with 5 rows (stations, matching
camtraps_soReta) and 120 columns (one per calendar
day from 01/01/2026 to 30/04/2026, column names "YYYY-MM-DD").
Values are 1 (camera active that day), 0 (camera not yet deployed,
already retrieved, or down due to a malfunction period), or NA
(before deployment/after retrieval, camtrapR's convention for "no
camera present at all" as opposed to "present but not working").
Source
Synthetic data generated for this package; see
data-raw/create_sample_data.R for the full generation
script (fixed random seed, fully reproducible; requires
camtrapR to regenerate, though not to use the resulting
object).
See Also
camtraps_soReta, the station table this
matrix was built from.
Example station table for soReta
Description
A small, entirely SYNTHETIC camera-trap station table, in the format
expected by camtrapR::cameraOperation(). Built specifically as
the example dataset for this package, so it never needs to depend on
camtrapR's own sample data (which lacks an individual-count column
and uses different species codes across examples).
Usage
camtraps_soReta
Format
A data frame with 5 rows and 7 columns:
- Station
station ID, "S_01" to "S_05".
- Setup_date
deployment date, "DD/MM/YYYY".
- Retrieval_date
retrieval date, "DD/MM/YYYY". All stations share the same retrieval date, 30/04/2026.
- Problem1_from,Problem1_to
start/end of the first malfunction period for that station, "DD/MM/YYYY", or "" if none.
- Problem2_from,Problem2_to
start/end of a second malfunction period, "DD/MM/YYYY", or "" if none. Only stations S_03 and S_05 have a second problem period in this example.
Source
Synthetic data generated for this package; see
data-raw/create_sample_data.R for the full generation script.
See Also
recordTable_soReta, the matching example
recordTable.
Extract, per species (and optionally per one or more groupings), a vector of times in radians
Description
Extract, per species (and optionally per one or more groupings), a vector of times in radians
Usage
extract_radians(
recordTable,
dateTimeCol = "DateTimeOriginal",
stationCol = "Station",
speciesCol = "Species",
threshold_min = 30,
group_cols = c(stationCol, speciesCol),
group_col = NULL,
independence_method = c("chain", "window"),
require_uninterrupted = FALSE
)
Arguments
recordTable |
camtrapR-style data.frame (e.g. output of recordTable()). |
dateTimeCol |
name of the date/time column (default "DateTimeOriginal"). |
stationCol |
name of the station column (default "Station"). |
speciesCol |
name of the species column (default "Species"). |
threshold_min |
independence threshold in minutes (default 30). |
group_cols |
vector of column names used to group events when computing independence (default c(stationCol, speciesCol)). |
group_col |
vector of one or more column names used to split each species' result into successive nested levels (e.g. "bimonth", or c("Station", "bimonth")). Default NULL = no splitting, a single vector per species. |
independence_method |
how consecutive photos of the same species are collapsed into one independent event, within each group_cols subsequence: "chain" (default) or "window". See build_site_block() docs for details. |
require_uninterrupted |
apply O'Brien et al. (2003)'s third independence criterion (default FALSE): two photos are only subject to the time threshold if no photo of ANY other species falls chronologically between them at that station (stationCol), regardless of group_cols. See build_site_block() docs. |
Details
The radians are in CLOCK TIME, not solar time. For comparisons across seasons or different latitudes, convert the result with activity::solartime() or overlap::sunTime() before passing it to densityPlot()/fitact() – this function does not do that.
Value
Named list per species. If group_col is NULL: result[[species]]
is a numeric vector of radians. If group_col has 1 element:
result[[species]][[group]]. If it has 2 or more: one further nested
level per column, in the same order as group_col.
Create a separate object in the environment for each vector in a nested list of radians
Description
Create a separate object in the environment for each vector in a nested list of radians
Usage
radians_to_env(
radians_list,
prefix = "Rad_",
sep = "_",
envir = parent.frame()
)
Arguments
radians_list |
(possibly nested) list produced by extract_radians(). |
prefix |
prefix for the created object names (default "Rad_"). |
sep |
separator between the pieces of the name (default "_"). |
envir |
environment in which to create the objects (default the environment from which you call the function). |
Value
(invisible) the vector of names of the created objects. The function is called for its side effect of creating the objects in envir, not for its return value.
Example individually-identifiable recordTable for soReta
Description
A small, entirely SYNTHETIC individual-level recordTable, in the
format expected by build_cmr_day()/build_cmr_block()
(the same shape as camtrapR's own recordTableIndividual()
output). Built by taking the "red deer" detections already present
in recordTable_soReta and assigning each one to one of
8 individually-recognizable deer, with unequal, realistic recapture
rates (a few "resident" individuals seen often, others seen only
once or twice) – purely for illustration, not derived from any real
survey. Unlike the CMR examples elsewhere in camtrapR-based
tutorials, this dataset requires no dependency on camtrapR's own
bundled data.
Usage
recordTableIndividuals_soReta
Format
A data frame with 103 rows and 4 columns:
- Station
station ID, matching
camtraps_soReta.- Species
always "red deer" in this dataset.
- Individual
individual ID, "RD_01" to "RD_08".
- DateTimeOriginal
date and time of the photo, POSIXct (UTC).
Source
Synthetic data generated for this package; see
data-raw/create_individuals_dataset.R for the full
generation script (fixed random seed, fully reproducible; run
after data-raw/create_sample_data.R, since it starts from
that script's recordTable_soReta object).
See Also
recordTable_soReta, the recordTable this
dataset's red deer detections were taken from; camtraps_soReta,
the matching example station table.
Example recordTable for soReta
Description
A small, entirely SYNTHETIC camtrapR-style recordTable: four species
(wolf, red fox, wild boar, red deer), detections spread across the
five stations in camtraps_soReta, only on days those stations
were actually active. Detection times are weighted towards night and
twilight hours. Individual counts (N_individuals) follow different
distributions per species – red fox and red deer mostly solitary
(max 2 and 4 respectively), wolf up to small-pack sizes (max 8), wild
boar in larger sounders on average (max 30) – purely for
illustration, not derived from any real survey.
Usage
recordTable_soReta
Format
A data frame with 404 rows and 4 columns:
- Station
station ID, matching
camtraps_soReta.- DateTimeOriginal
date and time of the photo, POSIXct (UTC).
- Species
one of "wolf", "red fox", "wild boar", "red deer".
- N_individuals
number of animals visible in that photo.
Details
Detections are clustered into "visits" of 1 to 4 photos rather than
spread one-per-day, so that most active days have no detection at
all, while the days that do often have several photos close together
in time – including two deliberately placed sequences (one for
"wolf" at station S_02, one for "wild boar" at station S_03) with
gaps of exactly 16 and 25 minutes between consecutive photos: with
the default 30-minute threshold, independence_method =
"chain" collapses each of these into a single event, while
"window" splits it into two – worked examples for the
vignette's discussion of independence_method/
require_uninterrupted.
Source
Synthetic data generated for this package; see
data-raw/create_sample_data.R for the full generation script
(fixed random seed, fully reproducible).
See Also
camtraps_soReta, the matching example station table.