get_explodata: Extract nests and non-nests from revisited locations
In picardis/nestR: Estimation of Bird Nesting from Tracking Data

get_explodata

R Documentation

Extract nests and non-nests from revisited locations

Description

get_explodata uses known nest locations to extract an equal number of true nests and non-nests from a set of revisited locations for exploration of parameter values.

Usage

get_explodata(
  candidate_nests,
  known_coords,
  known_ids,
  buffer,
  pick_overlapping = TRUE
)

Arguments

`candidate_nests`	`data.frame` of candidate nests output by `find_nests`
`known_coords`	`data.frame` of coordinates for known nests. Needs to include burst, long, lat.
`known_ids`	`data.frame` of location IDs for known nests. Needs to include burst and loc_id.
`buffer`	Integer. Buffer distance (in meters) used to select true nest location among candidates when `known_coords` is provided.
`pick_overlapping`	Logical. If `TRUE` (default), the non-nest is picked among those whose time range overlaps with the true nesting attempt.

Details

If no prior information is available to the user about which parameter values to use to filter nests among revisited locations, some exploration of the data is necessary. The objective of the exploration phase is to identify the set of parameter values that best discriminates between nests and non-nests in the species or population at hand.

Our suggested procedure consists in running a first coarse screening of revisited locations, using loose thresholds of behavioral parameters for filtering. For example, using min_consec = 1, min_top_att = 1, and min_days_att = 1 in find_nests. In most cases, previous knowledge about the biology of the species should allow the user to already provide values for sea_start, sea_end, and nest_cycle. The output of this first screening is a set of revisited locations at the buffer distance of choice, which should include some nests as well as other repeatedly visited locations that are not nests. Comparing the values of behavioral parameters at nests versus non-nests can inform the choice of parameter values for later analysis.

This procedure requires knowledge of true nest locations for at least a subset of the data. Given some data on known nest locations and the coarse-screening output of find_nests, the function get_explodata identifies true nests and an equal number of non-nests to compare them to.

Comparing behavioral parameter values at nests versus non-nests will allow the user to find the set of parameter values that best discriminates between them. The resulting set of parameters can then be used to find nests in new data or in a subset of data for which no prior information on nests is available.

The user can pass data on known nests as either coordinates or location IDs. Ideally, prior and independent information on nest locations is available for a subset of the data. In this case, we recommend that coordinates are passed to the function argument known_coords. When coordinates of true nests are not known a-priori but the user is able to visually inspect revisited locations and identify those that are true nests (for example because they fall within known colonies), providing location IDs for true nests in known_ids is an alternative option.

When passing known_coords, the user is required to also specify a value for buffer. Because of GPS error, the coordinates of the point representing the true nest in candidate_nests might not exactly match those of the known nest location. If coordinates of true nests are provided rather than location IDs, the function selects the true nest among the set of candidates by choosing the candidate with the most visits among those that fall within a buffer distance from the known nest location. We recommend using for this argument the same value used for argument buffer in find_nests.