Transect metrics from GPS session geometry

For structured project exports, each session may store a GPS track (session.geom, typically a GeoJSON LineString) linked from samples via sample.session. This function returns one row per session with line length, start/end coordinates, the earliest observation on the primary sample (lowest sample_id linked to the session), and the geodesic distance from the transect start to that observation.

Usage

obs_session_metrics(
  x,
  location = NULL,
  user = NULL,
  protocol = NULL,
  date = NULL,
  date_start = NULL,
  date_end = NULL
)

Arguments

x: Path to a project SQLite export, a project obs_df, or a tibble from obs_visits() / obs_samples().
location: Location id or name (partial match).
user: Observer id or name.
protocol: Protocol id or name.
date: Length-2 vector c(start, end) as "YYYY-MM-DD", or a single date.
date_start, date_end: Bounds on sample/visit dates (same as obs_samples()).

Value

A tibble with one row per session; see Output columns above.

Output columns

Column	Description
`visit_id`, `session_id`, `sample_id`	Primary identifiers (`sample_id` is the primary sample for first-obs metrics)
`visit_ids`, `sample_ids`	Semicolon-separated identifiers when a session spans multiple visits or samples
`n_samples`	Number of samples linked to the session
`n_visits`	Number of visits linked to the session
`counted`	Semicolon-separated `visit.counted` codes linked to the session
`length_m`	Geodesic length of `session.geom`
`start_lng`, `start_lat`, `end_lng`, `end_lat`	First and last vertices of the line
`first_obs_lng`, `first_obs_lat`	Earliest observation on the primary sample
`distance_to_first_obs_m`	Distance from transect start to that observation

Filters and geometry

Distances and lengths use WGS84 (EPSG:4326) via the suggested sf package, consistent with geodesic measures on geographic coordinates.

location, user, protocol and dates restrict which samples (and thus sessions) are included—the same semantics as obs_samples(). Pass a visit or sample tibble from obs_visits() or obs_samples() to reuse an existing filter; extra filter arguments are then ignored.

Only LineString geometries in session.geom are used. Sessions without a usable line are omitted with a warning. If the export has no session table, the function warns and returns zero rows.

For a step-by-step guide, see vignette("project-exports"). Schema details for session are in vignette("export-structure") (Appendix B).

Examples

if (FALSE) { # \dontrun{
obs_session_metrics("project-export.sqlite")
obs_session_metrics(db, protocol = "Road survey")

tracks <- obs_session_metrics(db, location = "North Ridge")
write.csv(tracks, "session_metrics.csv", row.names = FALSE)
} # }