Fitting Sightability Models • spdgt.sight

library(spdgt.sight)

Overview

This vignette covers fitting sightability models to estimate abundance using the SpeedGoat sightability API. Authentication is handled automatically - you will be prompted to log in when needed.

Prerequisites

Before fitting a model, ensure you have:

Completed survey data available
Identified your species, survey type, analysis unit, and model

# Look up required IDs
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)
model_id <- lkup_model_id("Mule Deer")

# Check available models
models <- sight_read_model(
  species = "Mule Deer",
  survey_type = "Sightability"
)
print(models)

Fitting a Sightability Model

Use sight_fit_model() to fit a sightability model and estimate abundance.

Spatial Focus Options

The spatial_focus parameter determines the level of aggregation for results:

"DAU" - Aggregate results to the analysis unit (DAU) level
"GMU" - Aggregate results to the management unit (GMU) level
"SubUnit" - Return results at the subunit level

Fitting at the DAU Level

# Using names
results <- sight_fit_model(
  species = "Mule Deer",
  spatial_focus = "DAU",
  bio_year = 2024,
  analysis_unit = "North Converse 755",
  survey_type = "Sightability",
  model = "Mule Deer"
)

# Using IDs
results <- sight_fit_model_id(
  species_id = species_id,
  spatial_focus = "DAU",
  bio_year = 2024,
  analysis_unit_id = dau_id,
  survey_type_id = survey_type_id,
  model_id = model_id
)

Fitting at the GMU Level

results <- sight_fit_model(
  species = "Mule Deer",
  spatial_focus = "GMU",
  bio_year = 2024,
  analysis_unit = "North Converse 755",
  survey_type = "Sightability",
  model = "Mule Deer"
)

Fitting at the SubUnit Level

results <- sight_fit_model(
  species = "Mule Deer",
  spatial_focus = "SubUnit",
  bio_year = 2024,
  analysis_unit = "North Converse 755",
  survey_type = "Sightability",
  model = "Mule Deer"
)

Understanding the Output

The model fit returns a flat tibble with context columns followed by estimation columns:

# View the results
print(results)

# Context columns: species_id, bio_year, analysis_unit_id, spatial_focus,
#   survey_type_id, model_id
# Estimation columns: Demographic, RawCount, Estimate, TotalVar, SE, LCL,
#   UCL, CV, and method-specific columns (SightInflation, SampInflation, etc.)

Working with Model Parameters

Reading Model Definitions

To understand available models and their structure:

# Get all models
models <- sight_read_model()

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

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

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

Reading Beta Coefficients

To examine the sightability model coefficients:

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

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

print(betas)

Reading Variance-Covariance Matrix

To get the variance-covariance matrix for model coefficients:

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

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

print(vcov)

Complete Model Fitting Workflow

Here’s a complete example:

library(spdgt.sight)

# 1. Set up parameters
species <- "Mule Deer"
survey_type <- "Sightability"
analysis_unit <- "North Converse 755"
bio_year <- 2024
model_name <- "Mule Deer"

# 2. Check that survey data exists
summaries <- sight_read_entries(
  species = species,
  survey_type = survey_type,
  analysis_unit = analysis_unit,
  bio_year = bio_year
)

if (nrow(summaries) == 0) {
  stop("No survey data found for the specified parameters")
}

print("Survey data found:")
print(summaries)

# 3. Review the model
model_info <- sight_read_model(name = model_name)
print("Model information:")
print(model_info)

# 4. Fit the model at DAU level
results_dau <- sight_fit_model(
  species = species,
  spatial_focus = "DAU",
  bio_year = bio_year,
  analysis_unit = analysis_unit,
  survey_type = survey_type,
  model = model_name
)

print("DAU-level results:")
print(results_dau)

# 5. Fit at GMU level for finer resolution
results_gmu <- sight_fit_model(
  species = species,
  spatial_focus = "GMU",
  bio_year = bio_year,
  analysis_unit = analysis_unit,
  survey_type = survey_type,
  model = model_name
)

print("GMU-level results:")
print(results_gmu)

Retrieving Survey Data for Custom Analysis

If you need the raw data for custom analysis:

# Get the combined design and observation data
data <- sight_read_data(
  species = "Mule Deer",
  survey_type = "Sightability",
  analysis_unit = "North Converse 755",
  bio_year = 2024
)

# Get model coefficients
betas <- sight_read_betas(model = "Mule Deer", includes = c("covar"))
vcov <- sight_read_vcov(model = "Mule Deer")

# Now you have everything needed for custom sightability analysis

You can also pass custom or modified data directly to sight_fit_model_id() via its data parameter. See vignette("custom-data") for the full schema reference, synthetic data examples, and guidance on ratio estimation.

Tips and Best Practices

Verify data availability - Use sight_read_entries() before fitting
Choose appropriate spatial focus - DAU for overall estimates
Review model assumptions - Check that the model is appropriate for your species and survey conditions
Cache IDs - Look up IDs once and reuse them with _id variants for efficiency in scripts