Segmenting NARWC line-transect data
Source:vignettes/segmenting-narwc-data.Rmd
segmenting-narwc-data.RmdWhat this package does
A density surface model needs survey effort cut into short pieces of
roughly equal length, called segments. Each segment has a
location, an amount of effort, and a count of what was seen along it.
distsamp builds that segment table from line-transect data
in the format of the North Atlantic Right Whale Consortium (NARWC)
sightings database.
The input format is defined in Kenney (2023), The North Atlantic
Right Whale Consortium Database: A Guide for Users and
Contributors, Version 8 (the “handbook”). The output can be passed
to Distance or dsm.
Read the data
read_narwc() standardises column names and types. It
accepts the handbook’s LAT_DD/LONG_DD and the
LATITUDE/LONGITUDE spelling used in extracts
from the database manager.
path <- system.file("extdata", "narwc-example.csv", package = "distsamp")
dat <- 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.
dim(dat)
#> [1] 113 30
head(dat[, c("FILEID", "EVENTNO", "TIME", "LATITUDE", "LEGTYPE", "LEGSTAGE", "SPECCODE")])
#> # A tibble: 6 × 7
#> FILEID EVENTNO TIME LATITUDE LEGTYPE LEGSTAGE SPECCODE
#> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>
#> 1 AA240401 1 120000 42.9 1 NA NA
#> 2 AA240401 2 120200 43.0 1 NA NA
#> 3 AA240401 3 120200 43.0 1 NA HUWH
#> 4 AA240401 4 120400 43 2 1 NA
#> 5 AA240401 5 120425 43.0 2 2 NA
#> 6 AA240401 6 120450 43.0 2 2 NAAll data in this vignette is synthetic.
narwc-example.csv is a two-day survey generated by
data-raw/make-fixture.R. It mirrors the hypothetical survey
in Figure 2 of the handbook: transits, survey lines, sightings sharing
an event number, a pilot sighting, a cross-leg, a break-off to circle,
and a line abandoned and re-flown later the same day. Positions, dates,
and animals are invented. Every line runs due north along one meridian
in 0.01-degree steps, so expected distances can be checked by hand.
No real NARWC records are distributed with the package or were used to develop it. The numbers here show the mechanics only; none is a result. Real data must be requested from the NARWC. Validation against a real extract is still an open item.
Handle columns a survey programme adds
Survey programmes add their own derived columns.
read_narwc() keeps the handbook columns, drops the rest,
and reports what it dropped:
ccs <- read.csv(path)
ccs$Tr_SIGHTING <- 1
ccs$IS_LAT <- ccs$LAT_DD
ccs$IS_LONG <- ccs$LONG_DD
kept <- read_narwc(ccs)
#> `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.
#> `read_narwc()` dropped 3 columns not in the NARWC handbook schema:
#> IS_LAT, IS_LONG, Tr_SIGHTING
#> 3 of these are declared by the "ccs" profile (Center for Coastal Studies, Cape Cod Bay).
#> Keep them with `profile = "ccs"`; see `narwc_profiles()`.narwc_profiles() lists what is known about each
programme’s columns, with a confidence level:
narwc_profiles("ccs")[, c("column", "role", "confidence")]
#> # A tibble: 8 × 3
#> column role confidence
#> <chr> <chr> <chr>
#> 1 IS_LAT passthrough confirmed
#> 2 IS_LONG passthrough confirmed
#> 3 IS_SPECCODE passthrough unconfirmed
#> 4 Tr_SIGHTING passthrough confirmed
#> 5 OBSSIGHT passthrough unconfirmed
#> 6 Effort_Type passthrough unconfirmed
#> 7 Date_UTC passthrough unconfirmed
#> 8 Time_UTC passthrough unconfirmedNaming the profile keeps them:
names(read_narwc(ccs, profile = "ccs"))[10:14]
#> `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.
#> [1] "LEGSTAGE" "LEGNO" "ALT" "BEAUFORT" "VISIBLTY"Keeping a column is not interpreting it. A profile is never applied
because a column name matched, and distsamp only carries
these columns. In a CCS file Tr_SIGHTING means “sighting
made from the track-line”, but another programme could use the same name
for something else. A column name is not a contract between
programmes.
Fill values recorded only when they change
NARWC often records a value once and leaves it blank until it
changes. For example, LEGTYPE is entered at the start of a
census line and left empty below. fill_narwc() carries that
state forward:
gappy <- data.frame(
FILEID = "A", DATE = as.Date("2024-04-01"), EVENTNO = 1:6,
LEGTYPE = c(2, NA, NA, NA, 1, NA),
BEAUFORT = c(2, NA, NA, 4, NA, NA)
)
fill_narwc(gappy)
#> `fill_narwc()` filled 8 values, grouped by FILEID, DATE.
#> carried forward: 8
#> LEGTYPE 4, BEAUFORT 4
#> # A tibble: 6 × 5
#> FILEID DATE EVENTNO LEGTYPE BEAUFORT
#> <chr> <date> <int> <dbl> <dbl>
#> 1 A 2024-04-01 1 2 2
#> 2 A 2024-04-01 2 2 2
#> 3 A 2024-04-01 3 2 2
#> 4 A 2024-04-01 4 2 4
#> 5 A 2024-04-01 5 1 4
#> 6 A 2024-04-01 6 1 4It differs from a bare tidyr::fill() in three ways.
It groups by file and day. Without grouping, the sea state from the last record of one day carries into the next, and a leg number crosses into another survey. A filled value cannot be told apart from a recorded one afterwards, so the error cannot be found later.
It refuses to fill sighting columns. Carrying
SPECCODE and NUMBER forward would copy one
group of three right whales onto every row until the next sighting:
fill_narwc(gappy, columns = "NUMBER")
#> Error in `fill_narwc()`:
#> ! These columns must not be carried forward: `NUMBER`.
#> They are per-record measurements, not survey state. Filling a sighting column replicates one detection onto every row beneath it; filling a position or time fabricates a measurement. See `?narwc_fill_columns`.It reports recovered and inferred values separately.
"downup" fills down, then up. The upward fills are values
before the first record of a group, which were never logged. Only the
downward fills recover recorded state, so the report counts the two
apart.
Filling LEGSTAGE is the least safe default. If a file
records 1 (begin line) and leaves the continuation rows
blank, filling down marks the whole line 1 instead of
2 (continue). On-effort eligibility is
LEGSTAGE == 2, so that line drops out of every distance
calculation. Check the per-column counts against what you expect.
Check the data
validate_narwc() reports problems without raising errors
or modifying the data.
validate_narwc(dat)
#> # A tibble: 1 × 6
#> check severity column n rows message
#> <chr> <chr> <chr> <int> <list> <chr>
#> 1 legstage_line_not_closed note LEGSTAGE 1 <int [1]> A line occupation …The fixture gives one note. A survey line was abandoned when the sea state rose, so it has no end-line record. Lines abandoned or re-flown later legitimately lack one, so this is a note, not a warning. On a line flown to completion, a missing end-line means the record is incomplete.
Real data typically also gives codes outside the handbook’s code
book, sightings recorded at line-boundary events, LEGSTAGE
sequences that do not close, and gaps in required fields. Each finding
names the rows involved:
broken <- dat
broken$LEGTYPE[1] <- 8 # not a NARWC LEGTYPE
broken$LONGITUDE <- abs(broken$LONGITUDE) # sign convention lost
issues <- validate_narwc(broken)
issues[, c("check", "severity", "column", "n")]
#> # A tibble: 4 × 4
#> check severity column n
#> <chr> <chr> <chr> <int>
#> 1 unknown_code warning LEGTYPE 1
#> 2 legstage_line_not_closed note LEGSTAGE 1
#> 3 positive_west_longitude warning LONGITUDE 113
#> 4 exact_position_far_from_event warning S_LAT/S_LONG 4
issues$message[1]
#> [1] "`LEGTYPE` contains values outside the handbook code book (permitted: 0, 1, 2, 3, 4, 5, 6, 7, 9)."Segment the survey
segment_survey() runs the whole pipeline.
segs <- segment_survey(dat, seg_length = 5, seed = 1)
segs
#> <distsamp_segments>
#> segments: 20
#> tracks: 7
#> total effort: 92.23 km
#> segment length: median 4.44 km, range 2.22-7.78 km
#> target length: 5 km seed: 1
#> species: FIWH, RIWH, SEWH
#> detections: 8 (8 with a perpendicular distance, m)The segments table has one row per segment:
head(segs$segments[, c("seg_id", "LEGNO3", "seg_eff", "mid_lat", "mid_lon", "wt_beaufort")])
#> # A tibble: 6 × 6
#> seg_id LEGNO3 seg_eff mid_lat mid_lon wt_beaufort
#> <chr> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 2024-04-01_2_1 1_2 7.78 43.0 -69 2
#> 2 2024-04-01_2_2 1_2 5.56 43.1 -69 2
#> 3 2024-04-01_2_3 1_2 3.33 43.1 -69 2
#> 4 2024-04-01_2_4 1_2 5.56 43.2 -69 2
#> 5 2024-04-01_4_1 2_3 4.44 43.3 -69.1 2
#> 6 2024-04-01_4_2 2_3 3.33 43.3 -69.1 2-
seg_eff: the segment’s realised length, in km. -
mid_lat/mid_lon: the point halfway along the segment’s effort. Use it for covariate lookups. -
wt_beaufort: mean sea state, weighted by the distance each record covers. This is the form to use as a detection covariate.
Counts are in a separate table, one row per segment per species:
head(segs$sightings)
#> # A tibble: 6 × 4
#> seg_id SPECCODE n_sightings n_animals
#> <chr> <chr> <int> <dbl>
#> 1 2024-04-01_2_1 RIWH 1 1
#> 2 2024-04-01_2_2 FIWH 1 3
#> 3 2024-04-01_2_2 RIWH 2 3
#> 4 2024-04-01_4_2 RIWH 2 5
#> 5 2024-04-02_1_3 RIWH 1 4
#> 6 2024-04-02_1_5 SEWH 1 2For a density surface model, spread them across columns:
wide <- segments_wide(segs)
head(wide[, c("seg_id", "seg_eff", "mid_lat", "mid_lon", "n_RIWH", "n_FIWH")])
#> # A tibble: 6 × 6
#> seg_id seg_eff mid_lat mid_lon n_RIWH n_FIWH
#> <chr> <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1 2024-04-01_2_1 7.78 43.0 -69 1 0
#> 2 2024-04-01_2_2 5.56 43.1 -69 3 3
#> 3 2024-04-01_2_3 3.33 43.1 -69 0 0
#> 4 2024-04-01_2_4 5.56 43.2 -69 0 0
#> 5 2024-04-01_4_1 4.44 43.3 -69.1 0 0
#> 6 2024-04-01_4_2 3.33 43.3 -69.1 5 0Reproducibility
Segmentation makes two random choices: which segment absorbs a
track’s leftover distance, and whether a segment that cannot match its
target exactly runs long or short. With a seed, a run
repeats exactly.
a <- segment_survey(dat, seg_length = 5, seed = 1)
b <- segment_survey(dat, seg_length = 5, seed = 1)
identical(a$segments, b$segments)
#> [1] TRUE
c <- segment_survey(dat, seg_length = 5, seed = 2)
identical(a$segments$seg_eff, c$segments$seg_eff)
#> [1] FALSEThe session’s own random stream is not changed.
Choose a distance method
dist_methods()
#> # A tibble: 3 × 3
#> method aliases description
#> <chr> <chr> <chr>
#> 1 haversine "" Haversine on a 111.12 km/degree sphere; stable at short ran…
#> 2 becker "eab" Becker's segchopr fn.grcirclkm: spherical law of cosines, 6…
#> 3 kenney "rdk" Kenney and Winn (1986): spherical law of cosines, 111.12 km…Becker’s segchopr routine and Kenney and Winn (1986) use
the same formula: the spherical law of cosines, scaled by 111.12 km per
degree. The choice between them does not change results:
gc_distance(43, -69, 44, -70, method = "becker") ==
gc_distance(43, -69, 44, -70, method = "kenney")
#> [1] TRUEBoth names are kept so existing scripts read sensibly and so you can
record which lineage you followed. The default,
"haversine", uses the same sphere but stays numerically
stable at the short ranges between consecutive records, where the law of
cosines loses precision.
segment_survey(dat, seg_length = 5, seed = 1, dist_method = "becker")$settings$dist_method
#> [1] "becker"Define effort
flag_effort() decides which records are on effort. The
defaults follow the CETAP standard: on a survey line
(LEGTYPE == 2), Beaufort 3 or less, below 1,200 ft, and
visibility of at least 2 nautical miles.
table(flag_effort(dat)$OnOff.Effort)
#>
#> 0 1
#> 12 101
table(flag_effort(dat, max_beaufort = 1)$OnOff.Effort)
#>
#> 0
#> 113VISIBLTY holds two encodings in one column. Since 2004
it is a distance in nautical miles. Before that it held a code, stored
as a negative number. -1 means clear for at least 2
nautical miles, which is good conditions, so a plain
VISIBLTY >= 2 test discards every legacy record.
visibility_ok(c(5, 1.5, -1, -2))
#> [1] TRUE FALSE TRUE FALSEDefine sightings
Only detections made during standard search effort belong in a density estimate. By default the package excludes:
- sightings by anyone other than an on-duty observer
(
LEGSTAGE == 6); - sightings found afterwards in a vertical photograph
(
LEGSTAGE == 7); - identifications that are only possible or unrecorded
(
IDRELof 1 or 9).
strict <- segment_survey(dat, seg_length = 5, seed = 1)
loose <- segment_survey(
dat, seg_length = 5, seed = 1,
sighting_args = list(legstage_exclude = numeric(0), idrel_keep = 1:3)
)
sum(strict$sightings$n_sightings)
#> [1] 8
sum(loose$sightings$n_sightings)
#> [1] 11A group sighted from the track and then circled for photographs has its position recorded off effort. These detections are attached back to the segment they came from. Following the CETAP rule, only further groups of the same species count with the original:
sapply(c("none", "same_species", "all"), function(m) {
s <- segment_survey(dat, seg_length = 5, seed = 1, circling = m)
sum(s$sightings$n_animals[s$sightings$SPECCODE == "RIWH"])
})
#> none same_species all
#> 12 13 13Perpendicular distances
The perpendicular distance is the distance from the
track-line to the animal, measured at right angles to the track. Surveys
that record the ANGLEL/ANGLER declination
angles get perpendicular distances computed automatically, in a
detections table shaped for a detection function.
head(segs$detections)
#> # A tibble: 6 × 13
#> seg_id DATE SPECCODE size distance distbegin distend side
#> <chr> <date> <chr> <dbl> <dbl> <dbl> <dbl> <chr>
#> 1 2024-04-01_2_1 2024-04-01 RIWH 1 229 NA NA right
#> 2 2024-04-01_2_2 2024-04-01 RIWH 2 132. NA NA left
#> 3 2024-04-01_2_2 2024-04-01 RIWH 1 397. NA NA right
#> 4 2024-04-01_2_2 2024-04-01 FIWH 3 629. NA NA right
#> 5 2024-04-01_4_2 2024-04-01 RIWH 3 61.4 NA NA left
#> 6 2024-04-01_4_2 2024-04-01 RIWH 2 855. NA NA right
#> # ℹ 5 more variables: distance_source <chr>, EVENTNO <dbl>, SIGHTNO <dbl>,
#> # circling <int>, break_off_distance <dbl>The geometry is handbook 8.A.2. The angle is measured below the
horizon when the sighting is abeam, so the distance is
ALT / tan(angle).
# 45 degrees below the horizon at 229 m puts the animal 229 m off the track
perp_distance(45, altitude = 229)
#> [1] 229
perp_distance(c(75, 60, 45, 30, 15), altitude = 229)
#> [1] 61.36037 132.21321 229.00000 396.63963 854.63963Angles replaced STRIP in 2022. Survey altitudes rose
once offshore wind turbines were in place. STRIP’s fixed
distance intervals shift with altitude; an angle does not.
Distances before 2022: STRIP
Angles exist only from 2022. The archive records right-angle distance in three other ways, each with its own function.
STRIP is an interval, not a point, read off
calibrated markings on the observation bubble. Handbook 8.A.31 defines
two code books. Which one applies depends on the programme, the date,
and the aircraft, so one code can mean different things:
strip_distance(c(5, 13), scheme = "cetap", units = "nmi")
#> # A tibble: 2 × 4
#> distbegin distend side scheme
#> <dbl> <dbl> <chr> <chr>
#> 1 0.125 0.25 left cetap
#> 2 1 2 left cetap
strip_distance(c(5, 13), scheme = "nlpsc", units = "nmi")
#> # A tibble: 2 × 4
#> distbegin distend side scheme
#> <dbl> <dbl> <chr> <chr>
#> 1 0.25 0.5 left nlpsc
#> 2 4 Inf left nlpscCode 13 is 1–2 nmi under CETAP and over 4 nmi under NLPSC. Reading a
code with the wrong book gives plausible but wrong distances, and
nothing downstream detects it. With scheme = "auto" the
book is chosen from the survey date. With neither a date nor a scheme,
the function errors rather than guess. narwc_strip_bins()
prints either book in full.
Exact sighting positions
Where S_LAT/S_LONG exist, the perpendicular
distance is measured, not inferred. exact_distance()
projects the sighting onto the track-line:
prepped <- flag_effort(make_leg_id(dat))
ex <- exact_distance(prepped)
subset(cbind(prepped["SPECCODE"], ex), !is.na(distance))
#> SPECCODE distance along side bearing
#> 9 RIWH 229.0000 0 right 0
#> 15 RIWH 132.2132 300 left 0
#> 65 RIWH 160.3475 0 left 0along is how far the aircraft was from abeam when the
sighting was logged. Measuring straight to the animal instead gives
sqrt(distance^2 + along^2). That radial distance is always
too large, which widens the fitted strip and biases density down. The
row with along of 300 m has a radial distance more than
twice its perpendicular one.
Sightings logged while circling
These are usually real on-effort detections: the animal was seen from
the track-line, which is why the aircraft left it.
circling_distance() ties each one to the
LEGSTAGE == 3 break-off record and measures from there:
circ <- circling_distance(flag_circling(make_leg_id(dat)))
subset(circ, !is.na(distance))
#> # A tibble: 1 × 7
#> distance along side radial bearing anchor_event position_source
#> <dbl> <dbl> <chr> <dbl> <dbl> <dbl> <chr>
#> 1 250. -400. right 472. 0 39 exactradial is the straight-line distance from the break-off
point. distance is that distance projected onto the census
line. This is a weaker source than the other three, because the position
is fixed minutes after detection and the animal has moved. Exclude these
from a detection function unless including them is a deliberate, stated
choice.
Distance units
ALT is in metres, so distances are in metres by default.
seg_eff is in kilometres. Passing both to
Distance::ds() without reconciling them scales density by
1000. Use distance_units = "km", or supply
convert_units (0.001 for distances in m and effort in
km).
segment_survey(dat, seg_length = 5, seed = 1,
distance_units = "km")$detections$distance[1:3]
#> [1] 0.2290000 0.1322132 0.3966396Circling detections have no distance
Circled animals still count towards a segment’s abundance. A position
logged off the track is not a perpendicular distance, so it must not be
fitted. By default (circling_distance = "with_group")
circled animals are added to the group they were counted with and get no
detection row of their own:
subset(segs$detections, circling == 1)
#> # A tibble: 0 × 13
#> # ℹ 13 variables: seg_id <chr>, DATE <date>, SPECCODE <chr>, size <dbl>,
#> # distance <dbl>, distbegin <dbl>, distend <dbl>, side <chr>,
#> # distance_source <chr>, EVENTNO <dbl>, SIGHTNO <dbl>, circling <int>,
#> # break_off_distance <dbl>Distances are restricted to on-effort census records by default. Handbook 8.A.31 notes that some teams record angles during transits and circling for practice, and those must not enter a detection function.
Plot the result
Four diagnostic views show what the tables make hard to see. They
need ggplot2 and return ordinary ggplot
objects.
plot(segs)
The track flown is pale grey, segment midpoints dark grey, and sightings are coloured by species. A failed segmentation is usually obvious here: midpoints along a line the aircraft never flew, or bunched where a track should have split.
Both layers are capped on purpose. Midpoints shrink as their number
grows, because 19,774 of them at a readable size cover the survey area
in solid black. Only the max_legend most-seen species keep
their own colour; the rest are grouped as “other”, so a survey with 36
species still has a readable legend. Nothing is dropped from the map.
species = "RIWH" pulls any one species back out.
plot(segs, what = "tracks")
The same positions, coloured by new_trackno. This view
shows whether track splitting worked. A break in effort should start a
new colour, and one colour should never span two places the aircraft
could not have flown between. Look at the fixture’s re-flown line.
Past max_legend tracks, colours repeat and the legend is
dropped. A 130-entry legend squeezes the map into a corner, and 130
colours cannot be told apart. Neighbouring tracks still differ, which is
what the view is for.
plot(segs, what = "effort")
Segment lengths against the target, with the tolerance band dashed. Some spread is expected, because the Becker method gives each track one absorbing segment that takes the remainder. Many segments outside the band are not expected.
plot(segs, what = "distances")
The detection-function diagnostic. Look at it before calling
Distance::ds(). Expect a shoulder near zero and a tail that
falls away.
Two cautions:
- A dip in the first bin need not be a sampling artefact. An aircraft cannot see the water directly beneath it, and the handbook says so outright for the Skymaster. That is a reason to truncate on the left, not to assume the animals were absent.
- A smooth curve is not evidence that
g(0) = 1(detection on the line is certain). Animals submerged when the aircraft passed leave no trace in this plot.
The axis stops at the 99th percentile. The subtitle states how many detections lie beyond it and how large the largest is. On one real archive, a single distance of six thousand kilometres set the scale and put all 2,170 real distances in the first bin. A distance that large is a broken record, not a wide detection, and the subtitle says so. Nothing is removed from the data, only from the view.
For a map with coastlines, pass the positions to sf.
Plot part of a survey
An archive spanning decades plots as a smear. Every plotting function
takes dates, years, and months.
These narrow together: years = 2019, months = 8 is August
2019, not all of 2019 plus every August.
plot_survey(air, "occupations", years = 2019, months = 8)
plot(segs, what = "tracks", dates = "2019-08-14")filter_days() makes the same selection without plotting.
Asking for days the data does not hold is an error that reports which
days the data covers.
Spatial output
pts <- segments_as_sf(segs, "midpoints")
lines <- segments_as_sf(segs, "lines")
lines[1:3, c("seg_id", "seg_eff")]
#> Simple feature collection with 3 features and 2 fields
#> Geometry type: LINESTRING
#> Dimension: XY
#> Bounding box: xmin: -69 ymin: 43 xmax: -69 ymax: 43.15
#> Geodetic CRS: WGS 84
#> # A tibble: 3 × 3
#> seg_id seg_eff geometry
#> <chr> <dbl> <LINESTRING [°]>
#> 1 2024-04-01_2_1 7.78 (-69 43, -69 43.01, -69 43.02, -69 43.03, -69 43.04, -…
#> 2 2024-04-01_2_2 5.56 (-69 43.07, -69 43.08, -69 43.09, -69 43.09, -69 43.09…
#> 3 2024-04-01_2_3 3.33 (-69 43.12, -69 43.13, -69 43.14, -69 43.15)Cropping applies to the whole result and keeps the tables consistent:
gom <- c(xmin = -69.05, xmax = -68.5, ymin = 42, ymax = 48)
nrow(crop_to_bbox(segs, gom)$segments)
#> [1] 16Write results
The package writes nothing to disk unless asked.
out <- file.path(tempdir(), "segments")
write_segments(segs, out)
list.files(out)
#> [1] "segments_detections.csv" "segments_points.csv"
#> [3] "segments_segments.csv" "segments_sightings.csv"
#> [5] "segments_tracks.csv"Prepare a real extract
The fixture is clean. A real NARWC extract is not, and the
preparation steps must run in a fixed order. Getting the order wrong
raises no error. prepare_survey() runs them:
air <- prepare_survey(dat, quiet = TRUE)
c(records = nrow(air), on_effort = sum(air$OnOff.Effort == 1))
#> records on_effort
#> 113 101In order, it builds line occupations, fills line state recorded only
at change points, classifies the platform by speed, keeps that
platform’s records, and flags effort. ?prepare_survey lists
which step depends on which. Two examples of why the order matters:
- Filtering out a vessel leg before occupations are built makes two occupations of one survey line adjacent. They merge, and the ferry between them counts as survey effort. On real data this gave 224.5 km where 4.4 km was correct.
-
LEGSTAGEis recorded when it changes, so most mid-line records carry none, and a right-angle distance needsLEGSTAGE == 2. On one archive this left 1,928 of 2,280 on-effort census sightings with no distance.
Then look at the data before trusting any number from it:
plot_survey(air, "occupations", coastline = FALSE)
A survey line drawn in three pieces, or three lines drawn as one,
shows here and not in a table. diagnose_pipeline() gives
the same check as numbers. The problems real extracts cause are listed
in docs/08-onboarding-a-real-extract.md.
If a view will not draw because the column it colours by does not
exist yet, use "positions". It needs only
LATITUDE and LONGITUDE, so it works on a file
that has not been prepared, or whose columns are not what was
expected.
plot_survey(air, "positions", sightings = TRUE, coastline = FALSE)
With sightings = TRUE this shows where the aircraft went
and what was seen. Sightings are taken before thinning and drawn as
outlined markers on their own scale, so they stand out from the effort.
Otherwise a few thousand sighting rows among three million would not
survive max_points.
Run the steps yourself
Every stage is exported, so you can intervene between them:
step <- dat |>
make_leg_id() |> # separate re-occupations of a line
flag_circling() |> # mark records taken while circling
flag_effort() |> # decide what is on effort
point_to_point_effort() |># great-circle distance along the track
split_tracks() # start a new track where effort breaks
tracks <- track_effort(step)
plan <- plan_segments(tracks, seg_length = 5, seed = 1)
head(plan)
#> # A tibble: 6 × 6
#> DATE new_trackno start_time track_effort seg_no tgtdist
#> <date> <chr> <dbl> <dbl> <int> <dbl>
#> 1 2024-04-01 2 120400 22.2 1 7.22
#> 2 2024-04-01 2 120400 22.2 2 5
#> 3 2024-04-01 2 120400 22.2 3 5
#> 4 2024-04-01 2 120400 22.2 4 5
#> 5 2024-04-01 4 123000 7.78 1 5
#> 6 2024-04-01 4 123000 7.78 2 2.78Citation
The segmentation method is Becker et al. (2010); the package is an
implementation of it. Cite both, and record the seed.
Without it the segmentation is not reproducible.
The published method states the target segment length and that
segments are cut from continuous effort. It does not say what happens to
the leftover distance at the end of a track. The tolerance test and the
random choice of an absorbing segment come from Becker’s
segchopr code. ?plan_segments is the
documentation of record for them.
References
Becker, E.A., Forney, K.A., Ferguson, M.C., Foley, D.G., Smith, R.C., Barlow, J. and Redfern, J.V. (2010) Comparing California Current cetacean-habitat models developed using in situ and remotely sensed sea surface temperature data. Marine Ecology Progress Series 413:163-183. https://doi.org/10.3354/meps08696
Becker, E.A., Forney, K.A., Redfern, J.V., Barlow, J., Jacox, M.G., Roberts, J.J. and Palacios, D.M. (2019) Predicting cetacean abundance and distribution in a changing climate. Diversity and Distributions 25:626-643. https://doi.org/10.1111/ddi.12867
Hedley, S.L. and Buckland, S.T. (2004) Spatial models for line transect sampling. Journal of Agricultural, Biological, and Environmental Statistics 9:181-199. https://doi.org/10.1198/1085711043578
Miller, D.L., Burt, M.L., Rexstad, E.A. and Thomas, L. (2013) Spatial models for distance sampling data: recent developments and future directions. Methods in Ecology and Evolution 4:1001-1010. https://doi.org/10.1111/2041-210X.12105
Kenney, R.D. (2023) The North Atlantic Right Whale Consortium Database: A Guide for Users and Contributors, Version 8. NARWC Reference Document 2023-01.
Kenney, R.D. and Winn, H.E. (1986) Cetacean high-use habitats of the northeast United States continental shelf. Fishery Bulletin 84:345-357.