Skip to contents

Read model definition

Source: R/sight_model.R
sight_read_model.Rd

Read model definition

Usage

sight_read_model(
  id = NULL,
  name = NULL,
  species = NULL,
  survey_type = NULL,
  sort = NULL,
  pages = list(omit = 1),
  includes = NULL,
  appends = NULL,
  dry_run = FALSE,
  ...
)

Arguments

id

ID of the model to read. If NULL, all models are returned.

name

Name of the model to read. If NULL, all models are returned.

species

Species name, must be used with survey_type

survey_type

Survey type name, must be used with species

sort

the name of columns to sort by

pages

A list with pagination options, see details

includes

A character vector of related resources to include, see details

appends

A character vector of fields to append to each model, see details

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

A tibble with columns id, name, type, definition, survey_type_ids, and metadata (list-column). When no models are found, returns a typed empty tibble.

Details

The pages argument is a named list with the following options:

  • omit: page number to omit, default is 1 which returns all records

  • size: number of records to return

  • number: the page number to return given the size

The includes argument is a character vector of related resources to include. Valid values are:

  • covars: include model covariates

  • surveyTypes: include survey types associated with the model

  • betaVars: include beta variables

  • countCategories: include count categories

  • covarBetas: include covariate betas

  • covarBins: include covariate bin definitions

  • covarCategories: include covariate category definitions

  • aerialSurveys: include associated aerial surveys

The appends argument is a character vector of fields to append to each model. Valid values are:

  • available_activities: append available activities for the model

  • available_vegetation: append available vegetation types for the model

Model metadata

Each model may have a metadata list-column containing a named list that controls estimation behavior and parameter mapping.

Control keys determine which estimation method sight_fit_model() uses:

method

Character. One of "sightability" (default when NULL/absent), "cochran" (plain ratio estimation), "quasibinomial" (quasi-binomial GLM ratio variance), or "corrected_cochran" (theta-corrected ratio estimation using a source sightability model). All ratio methods produce log-transform CIs (always positive, unbounded above).

source_model_id

Integer. Points wrapper models to a source sightability model whose betas, vcov, and covariates are used for estimation. Required when method = "corrected_cochran".

species

Character. Optional species filter used by downstream apps.

Parameter mapping keys connect demographic columns to IPM parameter IDs. Any key other than method, source_model_id, or species is treated as a parameter mapping. The key is the internal column name (e.g., "total", "males", "females", "youngs") or a ratio name ("MFRatio", "YFRatio"). The value is a colon-delimited string: "project_id:parameter_id:sex:age_class_id". Empty segments are treated as NA.

Examples of parameter mapping values:

  • "1:42::" – project 1, parameter 42, no sex or age class

  • "1:43:M:" – project 1, parameter 43, male

  • "1:44:F:3" – project 1, parameter 44, female, age class 3

Estimation dispatch:

  • method = NULL or "sightability": classical Wong estimator (abundance + ratios, lognormal CIs)

  • method = "cochran": plain Cochran ratios on raw counts (ratios only)

  • method = "quasibinomial": quasi-binomial GLM ratio variance (ratios only, tighter SEs than Cochran)

  • method = "corrected_cochran": inflates counts by detection correction theta from the source model, then computes Cochran ratios

  • Model type = "JAGS": Bayesian MCMC via rjags (uses definition field, not metadata)

Wrapper model pattern: a corrected_cochran model is a "wrapper" that points to a source sightability model via source_model_id. Betas, vcov, and covariate definitions come from the source model; only the estimation method differs. This avoids duplicating coefficient storage in the database.

Examples

if (FALSE) { # \dontrun{
# Read all models
sight_read_model()

# Read model by ID
sight_read_model(id = 1)

# Read model by name
sight_read_model(name = "Mule Deer")

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

# Add covariates and survey types to the output
sight_read_model(includes = c("covars", "surveyTypes"))

# Inspect model metadata
model <- sight_read_model(id = 17)
model$metadata[[1]]
# $method
# [1] "corrected_cochran"
# $source_model_id
# [1] 5

# Check the source model for a wrapper
sight_read_betas_id(model_id = model$metadata[[1]]$source_model_id)
} # }