Skip to contents

Getting Started with spdgt.sight

Source: vignettes/getting-started.Rmd
getting-started.Rmd

Overview

The spdgt.sight package provides utilities for interacting with SpeedGoat’s count data and sightability analysis APIs. It facilitates access to aerial survey data, models, and sightability analysis endpoints for wildlife population studies.

Authentication

The spdgt.auth package will authenticate you when needed. The user doesn’t need to do anything. Just call any function that requires authentication and it will prompt you to log in if necessary.

Understanding the Dual-Function Pattern

Most functions in spdgt.sight come in two variants: - Named variant (e.g., sight_read_data()) - accepts human-readable names - ID variant (e.g., sight_read_data_id()) - accepts database IDs directly

The named variants are more convenient for interactive use, while the ID variants are more efficient for programmatic use when you already have the IDs.

# Using names (convenient for interactive use)
data <- sight_read_data(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755",
  bio_year = 2024
)

# Using IDs (efficient for programmatic use)
data <- sight_read_data_id(
  species_id = 1,
  survey_type_id = 3,
  analysis_unit_id = 272,
  bio_year = 2024
)

Looking Up IDs

The package re-exports lookup functions from spdgt.core to help you find IDs for entities. Three patterns are available for each entity:

  • lkup_<entity>() - Returns a full tibble of all records
  • lkup_<entity>_id() - Converts a name to its database ID
  • lkup_<entity>_opts() - Returns a named vector for UI dropdowns

Available Lookup Functions 

# Species
lkup_species()                    # Get all species
lkup_species_id("Mule Deer")      # Get ID for a species name
lkup_species_opts()               # Get named vector for dropdowns

# Survey Types (requires species context)
species_id <- lkup_species_id("Mule Deer")
lkup_survey_type(species_id = species_id)
lkup_survey_type_id("Sightability", species_id = species_id)

# Analysis Units (DAU)
lkup_dau(species_id = species_id)
lkup_dau_id("North Converse 755", species_id = species_id)

# Management Units (GMU)
lkup_gmu(species_id = species_id)
lkup_gmu_id("61", species_id = species_id)

# Strata (requires species and survey type context)
lkup_strata(species_id = species_id, survey_type_name = "Sightability")
lkup_strata_id(
  "High", species_id = species_id,
  survey_type_name = "Sightability"
)

# Models
lkup_model()
lkup_model_id("Mule Deer")

Hierarchical Relationships

Some lookups require parent context because entities are hierarchical:

Species (root)
├── Survey Types
│   └── Strata
├── Analysis Units (DAU)
└── Management Units (GMU)

This means: - Looking up a survey type by name requires a species_id - Looking up a stratum by name requires both species_id and survey_type - Looking up an analysis unit or management unit requires a species_id

Using Filter Flags

When using named variants, the species and survey_type parameters serve two purposes:

  1. Lookup context - Required to resolve other names to IDs
  2. Filter - Passed to the API to filter results

Sometimes you need species only for lookup context without filtering by it. Use filter_species = FALSE or filter_survey_type = FALSE for this:

# Get all sightability summaries (not filtered by species)
# but still use species to look up survey_type_id
summaries <- sight_read_entries(
  species = "Mule Deer",
  survey_type = "Sightability",
  filter_species = FALSE
)

# The survey_type_id is resolved using species context,
# but only survey_type is used as a filter

Typical Workflow

A typical workflow for sightability analysis:

library(spdgt.sight)
library(spdgt.auth)

# 1. Find your species and survey type
species_id <- lkup_species_id("Mule Deer")
survey_type_id <- lkup_survey_type_id("Sightability", species_id = species_id)

# 2. Find your analysis unit
dau_id <- lkup_dau_id("North Converse 755", species_id = species_id)

# 3. Get survey summaries to see available data
summaries <- sight_read_entries(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755"
)

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

# 5. Or use IDs directly for efficiency
data <- sight_read_data_id(
  species_id = species_id,
  survey_type_id = survey_type_id,
  analysis_unit_id = dau_id,
  bio_year = 2024
)

Next Steps