Draw a season's sample for surveying in waves

Draws a season's sample once, through the sightability API: n base units per stratum, then a reserve of backups per stratum in the order they are to be used. Wave 1 is the base; sight_add_wave() takes each later wave from the reserve in that order, so nothing is ever redrawn.

Usage

sight_sample_season_id(
  survey_type_id,
  analysis_unit_id,
  bio_year,
  strata,
  method = c("grts", "random"),
  target = c("transects", "designs"),
  reserve = NULL,
  seed = NULL,
  dry_run = FALSE,
  verbosity = 0
)

sight_sample_season(
  species,
  survey_type,
  analysis_unit,
  bio_year,
  strata,
  method = c("grts", "random"),
  target = c("transects", "designs"),
  reserve = NULL,
  seed = NULL,
  dry_run = FALSE,
  verbosity = 0
)

Arguments

survey_type_id, analysis_unit_id

Integer ids of the survey type and analysis unit.

bio_year

Integer biological year.

strata

Data frame with stratum_id and the number of base units per stratum, in n or n_samples (the column sight_optimize_design_id() returns), and optionally reserve per stratum. Sizes are rounded to whole units; a stratum whose size rounds to 0, or whose include is FALSE, is left out of the season for good, with a warning.

method

"grts" (spatially balanced) or "random".

target

"transects" or "designs" (stratified subunits).

reserve

Backups per stratum where strata gives none. NULL (the default) means the whole rest of the frame for "random" and the base size again for "grts"; see Details.

seed

Integer seed, or NULL to have one drawn. The one used is returned in the season either way.

dry_run

Logical. Return the request instead of sending it.

verbosity

Integer, 0 to 3. Request/response detail to print.

species, survey_type, analysis_unit

Names, resolved to ids.

Value

A sight_season: a list with units (one row per base and reserve unit: its id, stratum_id, rank, role, wave, latitude, longitude), strata (stratum_id, N, n, reserve), and the seed, method, target, frame_hash, versions and survey ids that reproduce it. Base units carry wave = 1; reserve units have NA until a wave takes them.

Details

Base plus any leading run of the reserve is a valid sample of its size: with method = "random" a simple random sample, with method = "grts" a spatially balanced one. That is what lets you fly the base, then add waves as money, weather and aircraft allow, without spoiling the estimate – provided the rule for adding a wave does not depend on what earlier waves counted.

Heavier sampling for one species – pronghorn, say – is larger n in that species' strata of the one design, not a separate draw.

Set n and reserve before the season. With "random" a larger reserve only extends the order, but with "grts" the reserve is an input to the algorithm, so changing it, or any n, is a different draw. Keep the season object (saveRDS()): its seed and frame_hash are what reproduce it, and sight_check_season() confirms that they still do.

Size a GRTS reserve to the most the season could fly beyond the base, not the whole frame. spsurvey picks base and reserve together and then orders them, so the base alone is only approximately equal-probability, and less so the larger the reserve. Inclusion probabilities from sight_season_summary() are exact for "random" and approximate for "grts"; treat a GRTS pilot estimate as a planning figure.

See also

sight_add_wave(), sight_season_summary(), sight_check_season()

Examples

if (FALSE) { # \dontrun{
alloc <- sight_optimize_design_id(
  method = "fixed", value = 60, species_id = 13,
  survey_type_id = 9, analysis_unit_id = 340, bio_year = 2027
)
season <- sight_sample_season_id(
  survey_type_id = 9, analysis_unit_id = 340, bio_year = 2027,
  strata = alloc, method = "grts", reserve = 8
)
saveRDS(season, "season-2027.rds")
} # }