find_nests: Find nest locations from GPS data

In picardis/nestR: Estimation of Bird Nesting from Tracking Data

Find nest locations from GPS data

Description

find_nests finds nest locations from GPS data based on patterns of location revisitation

Usage

find_nests(
  gps_data,
  buffer,
  min_pts,
  sea_start,
  sea_end,
  nest_cycle,
  min_d_fix,
  min_consec,
  min_top_att,
  min_days_att,
  discard_overlapping = TRUE
)

Arguments

gps_data	data.frame of movement data. Needs to include burst, date, long, lat
buffer	Size of the buffer to compute location revisitation
min_pts	Minimum number of points within a buffer
sea_start	Character string. Earliest date to be considered within the breeding season. Month and day, format "mm-dd"
sea_end	Character string. Latest date to be considered within the breeding season. Month and day, format "mm-dd"
nest_cycle	Duration of nesting cycle
min_d_fix	Minimum number of fixes for a day to be retained if no nest visit was recorded
min_consec	Minimum number of consecutive days visited
min_top_att	Minimum percent of fixes at a location on the day with maximum attendance
min_days_att	Minimum percent of days spent at a location between first and last visit
discard_overlapping	If results include temporally overlapping attempts, select only one among those? Defaults to TRUE.

Details

Data passed to the argument gps_data needs to be split in individual-years labelled each as a separate burst. We recommend dividing the data so that seasonal nesting activities are contained within single bursts. Cutting data at a day that is not likely to overlap with nesting is best.

Data must include the following columns: a burst identifier (burst), date-time (date), and long/lat coordinates (long, lat).

Patterns of revisitation to repeatedly visited locations are used to identify potential nesting locations. Due to both movement and GPS error, recorded points around recurrently visited locations are expected to be scattered around the true revisited location. To account for this scattering, the user defines a buffer value which will be used to group points falling within a buffer distance from each other.

When grouping, several points peripheral to a true revisited location may compete in grouping points around them. We term these 'competing points'. If the buffers of two points do not overlap, those points are not competing. Among competing points, only one point is selected, chosen as the one that incorporates the most other points within its buffer. A top candidate is selected for each cluster of competing points, i.e., one representative for each cluster around a revisited location.

To speed up calculations, the user can define min_pts as the minimum number of points that need to fall within the buffer for a point to be considered as a potential nest candidate. This discards isolated points from consideration as revisited locations.

The arguments sea_start and sea_end are used to delimit the nesting season. The user can pass either a Julian day or a date. If inputting dates, the year can be a dummy year which will get automatically updated each time to the correct year for the current burst. If working with a species for which the temporal limits of the nesting season are not well-defined, the user can input a range of dates that covers the entire year. Nonetheless, we recommend ensuring that sea_start and sea_end are set so that nesting attempts are not split between bursts. For example, for a species that nests from October to September, enter October 1st as start date and September 30th as end date and not, for example, January 1st-December 31st.

The argument nest_cycle is the duration (in days) of a complete nesting attempt, i.e., the time necessary for an individual to successfully complete reproduction.

Once recurrently visited locations are identified, the function computes, for each of them:

• the first and last day when the location was visited;

• the total number of visits;

• the number of days in which it was visited;

• the percent of days visited between the days of first and last visit;

• the attendance (% of fixes at the location) on the day with the most visits;

• the longest series of consecutive days visited;

• the estimated start and end dates of the nesting attempt.

On days when no visit was recorded, two cases are possible: either the nest was truly not visited, or visits were missed. On days with few fixes, there is a higher chance of missing a visit given that it happened. Missed visit detections can interrupt an otherwise continuos strike of days visited. To counteract possible issues due to missed visit detections, the user can define min_d_fix as the minimum number of fixes that have to be available in a day with no visits for that day to be retained when counting consecutive days visited. If a day with no visits and fewer fixes than min_d_fix interrupts a sequence of consecutive days visited, it does not get considered and the sequence gets counted as uninterrupted.

The remaining arguments are used to filter results. The user can set minimum values for each of the following revisitation statistics:

• the longest series of consecutive days visited (min_consec);

• the attendance (% of fixes at the location) on the day with the most visits (min_top_att);

• the percent of days visited between the days of first and last visit min_days_att;

Among candidate nests, only those whose values for the above parameters exceed the user-defined minima are returned.

If the results include any temporally overlapping nesting attempts, the user can opt to only keep one among those. If discard_overlapping is set to TRUE (default), only the candidate nest with the most visits is kept among temporally overlapping ones, and the others get discarded. This is based on the rationale that an individual cannot simultaneously nest at more than one location. The location that is visited the most is assumed to be the most likely true nest. On the other hand, setting discard_overlapping to FALSE retains all candidate nests in the results.

After identifying all nests that correspond to the criteria defined in input, the function appends a new column to the original GPS data that flags fixes recorded at a nest with the location identifier of that nest. The result is a history of nest visits for each burst.

Value

Returns a list of two elements: first, 'nests', a data.frame of nest locations and associated revisitation stats; second, 'visits', a data.frame of nest revisitation histories.

picardis/nestR documentation built on July 2, 2024, 6:35 p.m.