Skip to contents

Reading Survey Data

Source: vignettes/reading-survey-data.Rmd
reading-survey-data.Rmd

Overview

This vignette covers the functions for reading survey data from the SpeedGoat API. Authentication is handled automatically by the spdgt.auth package - you will be prompted to log in when needed.

The package provides functions for reading:

  • Survey summaries
  • Survey entries (observations)
  • Survey designs
  • Combined data for sightability analysis

Survey Summaries

Use sight_read_surveys() to get brief summaries of available aerial surveys. This is useful for discovering what data exists before loading full observations.

# Get all summaries
summaries <- sight_read_surveys()

# Filter by species and year
summaries <- sight_read_surveys(
  species = "Mule Deer",
  bio_year = 2024
)

# Filter by survey type and analysis unit
summaries <- sight_read_surveys(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755"
)

The summary includes biological year, survey type, species, and analysis unit for each completed survey.

Survey Entries

Survey entries are individual observations or sightings recorded during a survey. Use sight_read_entries() to retrieve them.

# Read entries for a species and year
entries <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024
)

# Filter by management unit
entries <- sight_read_entries(
  species = "Mule Deer",
  management_unit = "61",
  bio_year = 2024
)

# Filter by analysis unit and survey type
entries <- sight_read_entries(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755",
  bio_year = 2024
)

# Additional filters
entries <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024,
  is_target_species = TRUE,  # Only target species observations
  is_selected = TRUE,        # Only selected subunits
  is_surveyed = TRUE         # Only surveyed subunits
)

Use the includes parameter to get related resources:

entries <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024,
  includes = c("aerialSurvey", "subunit", "species")
)

Appending Geometry

Use the appends parameter to include spatial data:

entries <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024,
  appends = c("polygon")  # WGS 84 (EPSG 4326)
)

Survey Designs

Survey designs define the sampling frame for a survey. Use sight_read_design() to retrieve designs without observation data.

# Read designs for a species and year
designs <- sight_read_design(
  species = "Mule Deer",
  bio_year = 2024
)

# Filter by survey type and analysis unit
designs <- sight_read_design(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755",
  bio_year = 2024
)

# Filter by selection/survey status
designs <- sight_read_design(
  species = "Mule Deer",
  bio_year = 2024,
  is_selected = TRUE,
  is_surveyed = TRUE
)
designs <- sight_read_design(
  species = "Mule Deer",
  bio_year = 2024,
  includes = c("surveyType", "subunit", "stratum")
)

Appending Fields 

designs <- sight_read_design(
  species = "Mule Deer",
  bio_year = 2024,
  appends = c("bio_year_start", "bio_year_end")
)

Designs with Entries

Use sight_read_design_entries() to get designs with their associated observations:

design_entries <- sight_read_design_entries(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755",
  bio_year = 2024
)

Note: This does not guarantee that observations outside the design are included. For comprehensive sightability data, use sight_read_data().

Combined Sightability Data

Use sight_read_data() to get data suitable for sightability analysis. This combines design and observation data with a full join:

data <- sight_read_data(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755",
  bio_year = 2024
)

This function: 1. Reads the design for the specified parameters 2. Reads the entries for the specified parameters 3. Performs a full join to combine them

This ensures all observations are included, even those outside the design.

Survey Column Mappings

Use sight_read_survey_cols() to get column mappings that define how database columns map to display names:

# Get all column mappings
cols <- sight_read_survey_cols()

# Filter by survey type
cols <- sight_read_survey_cols(
  species = "Mule Deer",
  survey_type = "Sightability"
)

# Filter by column name
cols <- sight_read_survey_cols(
  name = "total"
)

Models and Coefficients

Reading Model Definitions 

# Get all models
models <- sight_read_model()

# Get a specific model by ID
model <- sight_read_model(id = 1)

# Get a model by name
model <- sight_read_model(name = "Mule Deer")

# Get models for a species and survey type
models <- sight_read_model(
  species = "Mule Deer",
  survey_type = "Sightability"
)

# Include covariates and survey types
models <- sight_read_model(
  includes = c("covars", "surveyTypes")
)

# Append available activities and vegetation
models <- sight_read_model(
  appends = c("available_activities", "available_vegetation")
)

Reading Beta Coefficients 

# Get all beta coefficients
betas <- sight_read_betas()

# Get betas for a specific model
betas <- sight_read_betas(model = "Mule Deer")

# Get betas for a survey type
betas <- sight_read_betas(
  species = "Mule Deer",
  survey_type = "Sightability"
)

# Include covariate details
betas <- sight_read_betas(
  model = "Mule Deer",
  includes = c("covar")
)

Reading Variance-Covariance Matrix 

# Get variance-covariance matrix for a model
vcov <- sight_read_vcov(model = "Mule Deer")

# Include beta details
vcov <- sight_read_vcov(
  model = "Mule Deer",
  includes = c("betaOne", "betaTwo")
)

Pagination

All read functions support pagination through the pages parameter:

# Get first 100 records
entries <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024,
  pages = list(size = 100, number = 1)
)

# Get second page
entries_page2 <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024,
  pages = list(size = 100, number = 2)
)

# Get all records (default behavior)
entries_all <- sight_read_entries(
  species = "Mule Deer",
  bio_year = 2024,
  pages = list(omit = 1)  # Omit pagination
)

Using ID Variants

All read functions have _id variants for use when you already have IDs:

# Look up IDs once
species_id <- lkup_species_id("Mule Deer")
survey_type_id <- lkup_survey_type_id("Sightability", species_id = species_id)
dau_id <- lkup_dau_id("North Converse 755", species_id = species_id)

# Use IDs in subsequent calls (more efficient)
data <- sight_read_data_id(
  species_id = species_id,
  survey_type_id = survey_type_id,
  analysis_unit_id = dau_id,
  bio_year = 2024
)

entries <- sight_read_entries_id(
  species_id = species_id,
  survey_type_id = survey_type_id,
  analysis_unit_id = dau_id,
  bio_year = 2024
)