Sample subunits using GRTS or random sampling

Calls the sightability API to draw a sample of subunits from a survey design. Supports spatially-balanced GRTS sampling or simple random sampling within strata.

Usage

sight_sample_subunits(method, payload, dry_run = FALSE, ...)

Arguments

method

Character. Sampling method: "grts" (spatially-balanced) or "random".

payload

List describing the sampling frame. Must contain:

method

Character. "grts" or "random".

designs

List of design rows. Each element is a list with at least subunit_id (integer) and stratum_id (integer). For GRTS sampling, each element must also include a subunit list with a centroid GeoJSON string for spatial balancing.

proportions

List of stratum allocations. Each element is a list with stratum_id (integer), proportion (numeric, fraction of stratum to sample), and a nested stratum list containing at least id (integer, matching stratum_id) and can_sample (logical).

dry_run

If TRUE, print the HTTP request without sending it and return the request object invisibly. Useful for debugging.

...

Additional arguments passed to the underlying spdgt.auth function (e.g., verbosity, timeout).

Value

Tibble with one row per subunit and columns:

id

Integer. Design row identifier (if present in payload).

subunit_id

Integer. Subunit identifier.

stratum_id

Integer. Stratum identifier.

is_selected

Logical. Whether the subunit was selected in the sample.

is_surveyed

Logical. Whether the subunit was previously surveyed (passed through from payload).

Details

The payload is a nested list describing the sampling frame: which subunits exist, which stratum each belongs to, and what proportion of each stratum to sample. You can build this list yourself (see examples) or retrieve it from the database using the counts API.

Examples

if (FALSE) { # \dontrun{
# Build a payload manually for random sampling.
# This example has 6 subunits across 2 strata, sampling 50% of each.
payload <- list(
  method = "random",
  designs = list(
    list(subunit_id = 1L, stratum_id = 1L),
    list(subunit_id = 2L, stratum_id = 1L),
    list(subunit_id = 3L, stratum_id = 1L),
    list(subunit_id = 4L, stratum_id = 2L),
    list(subunit_id = 5L, stratum_id = 2L),
    list(subunit_id = 6L, stratum_id = 2L)
  ),
  proportions = list(
    list(
      stratum_id = 1L,
      proportion = 0.5,
      stratum = list(id = 1L, can_sample = TRUE)
    ),
    list(
      stratum_id = 2L,
      proportion = 0.5,
      stratum = list(id = 2L, can_sample = TRUE)
    )
  )
)

sight_sample_subunits(method = "random", payload = payload)
} # }