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
SPECCODEvalues to count, orNULLfor all.- seed
Integer RNG seed, or
NULLfor 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". Seegc_distance()anddist_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". Seeattach_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. Seeattach_circling_sightings().settings$circling_distancerecords 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) usesseg_length. Seeattach_circling_sightings().- distance_units
Units for perpendicular sighting distances computed from
ANGLEL/ANGLER:"m"(default) or"km". Note thatseg_effis always in km — seeperp_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. Seeplatform_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, indistance_source."circling"is accepted but has no effect here and warns: circling records reach the output only throughattach_circling_sightings(), which sets their distance fromcircling_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 whendathas noOnOff.Effortcolumn. 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
segmentsOne 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.sightingsOne row per segment per species.
detectionsOne row per qualifying sighting, with perpendicular
distanceandsidewhenANGLEL/ANGLERwere recorded. The input for a detection function.tracksOne row per continuous track.
pointsThe point-level data with segment assignments, for diagnostics and mapping.
call,settingsThe 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
make_leg_id()— separate re-occupations of the same survey line. Thennarwcr::fill_legstage(), unlessLEGSTAGE_FILLEDshows it has run. A warning is given if records move at another platform's speed, and circling records are flagged (CIRCLE).flag_effort()— decide which records are on effort.point_to_point_effort()— great-circle distance between consecutive on-effort positions. Then perpendicular sighting distances.split_tracks()— start a new track wherever effort breaks.track_effort()— total effort per continuous track.plan_segments()— how many segments, and how long each should be.cut_segments()— walk the records and make the cuts. Then circling sightings are added back.segment_midpoints()— the along-track midpoint of each segment.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