Skip to contents

What 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 NA

All 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 unconfirmed

Naming 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        4

It 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         2

For 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      0

Effort is conserved

Every kilometre of on-effort trackline is in exactly one segment.

sum(segs$tracks$track_effort)
#> [1] 92.2296
sum(segs$segments$seg_eff)
#> [1] 92.2296

Reproducibility

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] FALSE

The 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] TRUE

Both 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 
#> 113

VISIBLTY 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 FALSE

Define 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 (IDREL of 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] 11

A 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           13

Perpendicular 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.63963

Angles 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  nlpsc

Code 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       0

along 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 exact

radial 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.3966396

Circling 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] 16

Write 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       101

In 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.
  • LEGSTAGE is recorded when it changes, so most mid-line records carry none, and a right-angle distance needs LEGSTAGE == 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.78

Citation

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.