Computes the perpendicular distance from the track-line to each sighting that
carries an exact position in S_LAT/S_LONG (handbook 8.A.33, 8.A.34).
Usage
exact_distance(
dat,
by = NULL,
units = c("m", "km", "nmi"),
on_effort_only = TRUE
)Arguments
- dat
A data frame of NARWC survey data with
LATITUDE,LONGITUDE, and ideallyS_LAT/S_LONG. Data without the sighting-position columns comes back with the columns present and allNA.- by
Grouping columns identifying one occupation of a survey line, passed to
track_bearing().- units
"m"(default),"km", or"nmi".- on_effort_only
Restrict to on-effort census records. Default
TRUE.
Value
A tibble with one row per row of dat:
distancePerpendicular distance from the track-line.
alongSigned along-track offset between the logged position and the point where the sighting was abeam.
side"left","right","on-track", orNA.bearingThe track bearing used, for diagnosis.
Where this fits
This is the most direct of the three right-angle distance sources this package
supports. It measures the quantity a detection function is defined on rather
than inferring it. It needs a sighting position fixed independently (from a
GPS mark, a photograph, or a circling pass), so it exists only where the
survey recorded one. In the NARWC archive that is mostly the NLPSC-era and
later data. Where S_LAT/S_LONG and a declination angle both exist, they
are independent measurements of the same thing and check each other.
How it differs from the original scripts
The processing scripts this package was rewritten from computed the
great-circle distance from the event position straight to the sighting
position. That is a radial distance, not a perpendicular one, and it exceeds
the perpendicular distance by however far the aircraft was from being abeam
when the sighting was logged. This function projects onto the track instead,
and returns the along-track offset in along so the size of that difference
is visible rather than silently folded into the distance.
Restricted to census records
Like sighting_distances(), and for the same reason, distances are computed
only for on-effort records on a census line at LEGSTAGE == 2 by default.
Off the census line there is no track-line to be perpendicular to. A position
logged while circling has a defined distance to the animal but no useful
perpendicular distance. on_effort_only = FALSE computes them anyway; this
is useful for diagnostics and not appropriate for fitting.
References
Kenney, R.D. (2023) The North Atlantic Right Whale Consortium Database: A Guide for Users and Contributors, Version 8, sections 8.A.33 and 8.A.34. NARWC Reference Document 2023-01.
Examples
path <- system.file("extdata", "narwc-example.csv", package = "distsamp")
dat <- flag_effort(make_leg_id(read_narwc(path)))
#> `read_narwc()` renamed 2 columns:
#> LAT_DD -> LATITUDE
#> LONG_DD -> LONGITUDE
#> All matched an exact entry in the alias table; `narwc_column_mapping()` returns this, and `quiet = TRUE` silences it.
d <- exact_distance(dat)
cbind(dat[!is.na(d$distance), c("SPECCODE", "S_LAT", "S_LONG")],
d[!is.na(d$distance), c("distance", "along", "side")])
#> SPECCODE S_LAT S_LONG distance along side
#> 1 RIWH 43.0400 -68.99718 229.0000 0 right
#> 2 RIWH 43.0927 -69.00163 132.2132 300 left
#> 3 RIWH 43.0700 -68.80198 160.3475 0 left