get_ebird_coverage() retrieves the per-timestep eBird model coverage
stored in a BirdFlow model. Each cell–timestep combination records whether
that cell fell within eBird's modeled extent at that timestep.
Value
NA (with a warning) if the model lacks coverage metadata.
Otherwise the return type depends on format:
"SpatRaster"returns a multi-layer terra::SpatRaster with one logical layer per timestep. Layer names match the timestep labels (e.g."January 4"with the defaulttime_format)."array"returns the 3-D logical array[row, col, time], with timestep labels applied to the"time"dimension."dataframe"returns a long data.frame suitable for plotting withggplot2::geom_raster(), with one row per cell × timestep and columns:row,col— raster row and column indices.x,y— cell-center coordinates in the model CRS.i— location index inbf;NAfor cells outside the mask.timestep— canonical timestep label (e.g."t1").label—time_format-formatted timestep label (e.g."January 4").coverage— logical coverage value.
Details
Coverage metadata is captured by preprocess_species() and is absent from
models preprocessed before BirdFlowR 0.1.0.9081. For such models
get_ebird_coverage() returns NA with a warning.
Timestep labels in the "time" dimension of "array" output and layer
names of "SpatRaster" output follow
birdflow_options("time_format"), the same as
get_distr() and get_dynamic_mask(). In "dataframe" output the
canonical labels ("t1", "t2", ...) are always in the timestep
column, with the time_format-formatted version in label. The
internal, canonical labels are always used in metadata$ebird_coverage
itself; only the labels returned here change.
See also
preprocess_species() which captures this metadata,
get_mask() for the static model mask,
birdflow_options() for time_format.
Examples
if (FALSE) { # \dontrun{
bf <- preprocess_species("amewoo")
cov <- get_ebird_coverage(bf) # SpatRaster, one layer per week
arr <- get_ebird_coverage(bf, "array") # raw 3-D logical array
df <- get_ebird_coverage(bf, "dataframe") # long data frame for ggplot2
} # }
