Skip to contents

Filter Nesting Attempts Based on Expected Nest Phenological Periods

Source: R/nw.filterphenology.R
nw.filterphenology.Rd

To provide additional checks on data quality before analysis, an analyst may want to filter out nesting attempts which were recorded to have nesting phenologies of unexpectedly long lengths. This function allows an analyst to specify species-specific values for nest phenologies using expected days in the lay, incubation, nestling, and total nesting periods. By defining these allowable time frames an analyst can flag or remove "run-on" nest attempts or nests which do not match the specie's life history.

Usage

nw.filterphenology(data, mode, max_phenology, trim_to_active, output = NULL)

Arguments

data

dataframe; A dataframe of merged NestWatch attempt and visits data. Date columns must have class Date and Datetime columns must have class POSIXct.

mode

"flag" or "remove"; A character string defining if the analyst wants the identified nesting attempts to be flagged with "FLAGGED" in a new column, or removed from the dataset.

max_phenology

dataframe; A simple dataframe with one row for each species of interest and the following column structure:

  • Species: The 6-letter species code for each species.

  • Lay: The number of days representing the maximum expected laying period for each species.

  • Incubation: The number of days representing the maximum expected incubation period (between clutch complete and hatch) for each species.

  • Nestling: The number of days representing the maximum expected nesting period (hatch and last fledge) for each species.

  • Total: The number of days representing the maximum expected total nesting period (spanning first initial nest building to last fledge) for each species.

trim_to_active

logical; TRUE or FALSE indicating if nest check data should be trimmed to include only those rows where the nest was active (in build, lay, incubation, presence of life young). The first check observing a fledge or fail event is retained, but subsequent checks would be targeted for flag/removal. Flag/removal follows mode.

output

character; An optional character string to custom name the output dataframe

Value

dataframe

Details

This function calculates the number of days between First.Lay.Date, Hatch.Date, and Fledge.Date date values, comparing each to the user-provided acceptable date spans for each nest phase. Not all attempts contain these summary dates. An analyst may choose to explore nw.estclutchsize, nw.estfirstlay, nw.esthatch, and nw.estfledge functions to estimate these summary dates from the individual nest visit data prior to using this function. As an additional check, this function calculates the date span between the first occurrence of an incomplete nest, complete nest, observed egg, or observed young and last active date (either the last observation of eggs/live young or the first 0-egg/young count indicating fail/fledge) and compares this date span to the user-provided "total nesting period" value.

Examples

# Create phenology dataframe
phenology <- data.frame(species = c("carwre"),
                        lay = c(7),          # max observed
                        incubation = c(20),  # mean plus some extra
                        nestling = c(20),    # mean plus some extra
                        total = c(50))       # mean plus some extra


# Simplified NestWatch dataset with nest summary dates
# Attempts 3 & 4 should be flagged (too long in incubation and nestling phases respectively)
data <- data.frame(Attempt.ID = c("1", "2", "3", "4"),
                   Species.Code = rep("carwre", 4),
                   First.Lay.Date = as.Date(c("2024-05-01", "2024-05-01",
                                              "2024-05-01", "2024-05-01")),
                   Hatch.Date = as.Date(c("2024-05-20", "2024-05-21", "2024-06-10", "2024-05-21")),
                   Fledge.Date = as.Date(c("2024-06-05", NA, "2024-06-25", "2024-06-30")),
                   Visit.Datetime = c(rep(NA, 4)),
                   Outcome = c("s1", "f", "s1", "s1"),
                   Nest.Status = rep(NA, 4))
nw.filterphenology(data = data, max_phenology = phenology, mode = "flag")
#> Error in nw.filterphenology(data = data, max_phenology = phenology, mode = "flag"): Column 'Visit.Datetime' must be of class 'POSIXct' or 'POSIXt'.


# Simplified NestWatch dataset without nest summary dates
# (will look at total nest attempt duration from visit dates)
# Attempt "2" should be flagged as being too long.
data <- data.frame(Attempt.ID = c("1", "1", "2", "2"),
                   Species.Code = rep("carwre", 4),
                   First.Lay.Date = as.Date(rep(NA, 4)),
                   Hatch.Date = as.Date(rep(NA, 4)),
                   Fledge.Date = as.Date(rep(NA, 4)),
                   Visit.Datetime =
                   as.POSIXct(c("2024-05-01", "2024-06-15",
                                "2024-05-01", "2024-07-30")),
                   Outcome = c("s1", "s1", "s1", "s1"),
                   Nest.Status = rep(NA, 4))
nw.filterphenology(data = data, max_phenology = phenology, mode = "flag")
#> Error in pull(., Visit.ID): Can't extract column with `!!enquo(var)`.
#> ✖ Subscript `!!enquo(var)` must be a location, not an integer `NA`.