Skip to contents

Runs the whole segmentation pipeline: identify line occupations, flag effort, accumulate along-track distance, split lines where effort breaks, plan how many segments each continuous track carries, cut them, and summarise sightings and conditions onto each segment.

Usage

segment_survey(
  dat,
  seg_length,
  species = NULL,
  seed = NULL,
  seg_tol_frac = 0.5,
  min_track_km = 1,
  min_segment_km = 1,
  dist_method = c("haversine", "becker", "kenney", "eab", "rdk"),
  circling = c("same_species", "all", "none"),
  circling_distance = c("with_group", "break_off"),
  circling_max_gap_km = NULL,
  distance_units = c("m", "km"),
  platform = c("aerial", "vessel", "ship"),
  distance_sources = NULL,
  effort_args = list(),
  sighting_args = list()
)

Arguments

dat

NARWC survey data, ideally from read_narwc().

seg_length

Target segment length in km.

species

Character vector of SPECCODE values to count, or NULL for all.

seed

Integer RNG seed, or NULL for unseeded (not reproducible).

seg_tol_frac

Passed to plan_segments().

min_track_km

Passed to track_effort().

min_segment_km

Passed to cut_segments().

dist_method

Great-circle distance method: "haversine" (default), "becker", or "kenney". See gc_distance() and dist_methods(). Becker and Kenney are the same formula and give identical results.

circling

How to handle sightings recorded while circling off the census track: "same_species" (default), "all", or "none". See attach_circling_sightings().

circling_distance

What an attached circling record carries: "with_group" (default) gives it no distance and no detection of its own, adding the animals to the group they were counted with instead; "break_off" makes it a detection of its own, at the perpendicular distance of its exact position (S_LAT/S_LONG) from the census line where one exists, and otherwise at the great-circle distance from where the aircraft left the line. See attach_circling_sightings(). settings$circling_distance records which was used.

circling_max_gap_km

Furthest, in km, that the on-effort group may have been seen from the break-off for circled animals to be counted with it. NULL (default) uses seg_length. See attach_circling_sightings().

distance_units

Units for perpendicular sighting distances computed from ANGLEL/ANGLER: "m" (default) or "km". Note that seg_eff is always in km — see perp_distance().

platform

"aerial" (default), "vessel", or "ship" as a synonym for "vessel". Sets the effort criteria and the distance sources together, and decides which platform the speed check expects to find. See platform_defaults().

distance_sources

Precedence order over the right-angle distance sources, passed to sighting_distances(). NULL (default) takes the platform's order — c("angle", "exact", "strip") for an aircraft, "exact" for a vessel. Each detection records which source supplied it, in distance_source. "circling" is accepted but has no effect here and warns: circling records reach the output only through attach_circling_sightings(), which sets their distance from circling_distance. circling_distance = "break_off" already uses the perpendicular distance wherever an exact position exists.

effort_args

Named list of arguments for flag_effort(), used only when dat has no OnOff.Effort column. Merged over the platform's own defaults, so naming an argument here overrides it.

sighting_args

Named list of arguments for segment_sightings().

Value

An object of class distsamp_segments: a list with

segments

One row per segment — seg_id, DATE, FILEID, LEGNO, LEGNO3, new_trackno, seg_no, seg_eff (km), mid_lat, mid_lon, mean_beaufort, wt_beaufort, n_records, events, case, start_time.

sightings

One row per segment per species.

detections

One row per qualifying sighting, with perpendicular distance and side when ANGLEL/ANGLER were recorded. The input for a detection function.

tracks

One row per continuous track.

points

The point-level data with segment assignments, for diagnostics and mapping.

call, settings

The call and the parameters used.

Details

This is the function most users want. The individual steps are exported too, so you can run them yourself when you need to intervene between stages.

Pipeline

  1. make_leg_id() — separate re-occupations of the same survey line. Then narwcr::fill_legstage(), unless LEGSTAGE_FILLED shows it has run. A warning is given if records move at another platform's speed, and circling records are flagged (CIRCLE).

  2. flag_effort() — decide which records are on effort.

  3. point_to_point_effort() — great-circle distance between consecutive on-effort positions. Then perpendicular sighting distances.

  4. split_tracks() — start a new track wherever effort breaks.

  5. track_effort() — total effort per continuous track.

  6. plan_segments() — how many segments, and how long each should be.

  7. cut_segments() — walk the records and make the cuts. Then circling sightings are added back.

  8. segment_midpoints() — the along-track midpoint of each segment.

  9. segment_sightings() — counts and conditions per segment.

Steps 1 and 2 are skipped when the input already carries LEGNO3 or OnOff.Effort respectively, so you can substitute your own definitions.

Aerial or vessel

Segmentation itself does not depend on the platform: great-circle distance between fixes, splitting at breaks in effort, and cutting a track into lengths work the same for a ship as for a plane. Two things do depend on it: the effort criteria that decide which records count, and which right-angle distance sources exist. platform sets both at once. Setting one without the other gives a vessel's records an aircraft's criteria, and so a survey with no effort at all. See platform_defaults().

Reproducibility

Segmentation makes two random choices: which segment absorbs a track's leftover distance, and whether a segment that cannot land exactly on its target runs slightly long or slightly short. Pass a seed to make a run repeatable. The calling session's RNG state is never disturbed.

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. doi:10.3354/meps08696

Hedley, S.L. and Buckland, S.T. (2004) Spatial models for line transect sampling. Journal of Agricultural, Biological, and Environmental Statistics 9:181-199. doi: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. doi: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. University of Rhode Island, Graduate School of Oceanography.

See also

segments_wide() for a segment table with one count column per species, which is the shape dsm expects.

Examples

path <- system.file("extdata", "narwc-example.csv", package = "distsamp")
segs <- segment_survey(read_narwc(path), seg_length = 5, seed = 1)
#> `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.
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)
segs$segments[, c("seg_id", "seg_eff", "mid_lat", "mid_lon")]
#> # A tibble: 20 × 4
#>    seg_id         seg_eff mid_lat mid_lon
#>    <chr>            <dbl>   <dbl>   <dbl>
#>  1 2024-04-01_2_1    7.78    43.0   -69  
#>  2 2024-04-01_2_2    5.56    43.1   -69  
#>  3 2024-04-01_2_3    3.33    43.1   -69  
#>  4 2024-04-01_2_4    5.56    43.2   -69  
#>  5 2024-04-01_4_1    4.44    43.3   -69.1
#>  6 2024-04-01_4_2    3.33    43.3   -69.1
#>  7 2024-04-01_6_1    4.44    43.4   -69.1
#>  8 2024-04-01_6_2    4.44    43.4   -69.1
#>  9 2024-04-02_1_1    3.33    43.0   -68.8
#> 10 2024-04-02_1_2    4.44    43.0   -68.8
#> 11 2024-04-02_1_3    5.56    43.1   -68.8
#> 12 2024-04-02_1_4    4.44    43.1   -68.8
#> 13 2024-04-02_1_5    6.67    43.2   -68.8
#> 14 2024-04-02_1_6    4.44    43.2   -68.8
#> 15 2024-04-02_1_7    4.44    43.3   -68.8
#> 16 2024-04-02_2_1    3.33    43.4   -68.7
#> 17 2024-04-02_4_1    5.56    43.4   -68.6
#> 18 2024-04-02_4_2    2.22    43.4   -68.6
#> 19 2024-04-02_5_1    3.33    43.5   -68.7
#> 20 2024-04-02_5_2    5.56    43.5   -68.7