
Expand Site and Survey Covariates into GDR Intervals
Source:R/expand_gdr_intervals.R
expand_gdr_intervals.RdCopy chosen site covariates, or covariates recorded once per visit, into
the observation table of an unmarkedFrameGDR, which has one row per
survey and removal interval. A removal formula reads its covariates from
that table, so a covariate constant within a survey, such as the observer,
must be repeated there before you can use it in the removal formula. The
function also adds the interval number and returns a copy of the frame
with a record of how every row was aligned.
Arguments
- object
An
unmarkedFrameGDRwith its original counts and its site, yearly and observation covariates.- event_keys
Data frame with one row per survey event, in the frame's order (all primary periods of the first frame row, then the second, and so on). Include completed surveys with zero counts. Use the original survey identifiers.
- event_id
Character vector naming the column(s) of
event_keysthat identify a survey.- interval_units
Character string naming the time unit of the removal intervals, such as
"minutes". Interval lengths are kept, not converted.- site_covariates
Character vector naming the site covariates (
siteCovs) to repeat. The default is none. Name an element to give the copy a new name, for examplec(rem_forest = "forest", rem_observer = "Observer"). Unnamed elements keep the source name. Nothing is inferred from model formulas, so list every covariate you need.- yearly_covariates
Character vector naming covariates in the frame's yearly table (
yearlySiteCovs, one row per primary period) to repeat, with the same naming convention. The default is none. Despite the name, these rows are primary periods (visits), not necessarily years.- interval
Character string, default
"interval". The name of the new column holding the interval number (1, 2, ...). It must differ from the event keys and from the other new columns.- site_id
Optional column(s) of
event_keysthat identify the physical site, passed toprepare_gdr_intervals()andvalidate_unmarked_data().- effort
Optional numeric vector of survey effort, one value per event, passed to
validate_unmarked_data(). Positive values mark completed surveys, zero marks unsurveyed events andNAmarks unknown effort.- expected_event_keys
Optional independent event list in frame order, passed to
validate_unmarked_data().
Value
A list of class msr_gdr_intervals, as from
prepare_gdr_intervals(): data is the copied frame with the new
observation columns, survey_audit is the survey audit, alignment
records which input row fills each observation row, and protocol
records units, interval lengths and the added columns. In addition,
protocol$expanded_covariates is a data frame with one row per copied
covariate: source_table ("site" or "yearly"), the source column
and its target name in the observation table. With no covariates
selected, only the interval column is added. fit_eligibility_established
is always FALSE.
Why repeat covariates
When the removal formula contains a random effect, unmarked evaluates
the random-effect part on the observation table, and that step also needs
the formula's fixed covariates there. Repeating only an observer label can
therefore leave a
formula such as ~ rem_forest + I(interval == 1) + (1 | rem_observer)
without rem_forest. Select every survey-constant covariate the
observation formula needs.
How values are repeated
A site covariate is repeated for every primary period and interval at that
site. A yearly covariate is repeated only for the intervals of its own
primary period. Column classes, matrix columns, factor levels, contrasts
and missing values are kept. Nothing is standardized, imputed or dropped,
and the original covariate tables, counts, distance bands and interval
lengths are unchanged. Existing observation columns cannot be overwritten.
For covariates that change from one interval to the next, use
prepare_gdr_intervals() directly.
Name copies by role
Give a copy a new name when the same field plays different roles, for
example forest in the abundance formula and rem_forest in the removal
formula. A copy holds the values present when it was made. If you later
change the site covariate, for example while estimating its scale of
effect, the copy does not change with it. multiScale_optim() also stops
if a covariate whose scale it estimates shares its name with a column in
the observation or yearly tables, so new names avoid that conflict.
Aligning the data does not show that a model fitted to it converges or
that its parameters are identifiable. See the "Add covariates for the time
intervals" section of
vignette("v12-distance-removal", package = "multiScaleR") for a worked
example.
Examples
# Two surveys, two distance bands and three removal intervals
frame <- unmarked::unmarkedFrameGDR(matrix(0, 2, 2), matrix(0, 2, 3),
siteCovs = data.frame(forest = c(.2, .8), Observer = factor(c("A", "B"))),
dist.breaks = c(0, 25, 75), unitsIn = "m", period.lengths = c(1, 2, 1))
keys <- data.frame(survey = c("s1", "s2"))
# Copy forest and observer into the interval table under new names
prepared <- expand_gdr_intervals(frame, keys, "survey", "minutes",
site_covariates = c(rem_forest = "forest", rem_observer = "Observer"))
# One row per survey and interval, ready for a removal formula such as
# ~ rem_forest + I(interval == 1) + (1 | rem_observer)
unmarked::obsCovs(prepared$data)
#> interval rem_forest rem_observer
#> 1 1 0.2 A
#> 2 2 0.2 A
#> 3 3 0.2 A
#> 4 1 0.8 B
#> 5 2 0.8 B
#> 6 3 0.8 B
prepared$protocol$expanded_covariates
#> source_table source target
#> 1 site forest rem_forest
#> 2 site Observer rem_observer