LEGSTAGE marks what is happening to a survey line — it begins (1),
continues (2), breaks off to circle (3), resumes (4), ends (5). Programmes
record it when it changes, so a record taken mid-line often carries none
at all. This fills in the state those records were in.
Arguments
- dat
A data frame with
LEGSTAGE, in survey order — frommake_leg_id(), which sorts.- by
Columns identifying one line occupation, so a state never carries across a break.
NULL(default) usesLEGNO3when present, elseDATEandFILEID.- quiet
Suppress the report of how many were filled. Default
FALSE.
Value
dat with LEGSTAGE filled where the state is known, and a logical
LEGSTAGE_FILLED marking every record this function wrote to.
Why this is not fill_narwc()
Carrying LEGSTAGE forward as a value is wrong. 1 means "begin line", an
event; copying it onto the next thousand records claims the line began a
thousand times, and since 1 -> 1 is not a legal transition it manufactures
the sequence errors it looks like it should fix.
What carries forward is the state, not the code. Handbook 8.A.20:
| after 1 begin | the line is continuing, so 2 |
| after 2 continue | still continuing, 2 |
| after 4 resume | continuing again, 2 |
| after 3 break off | off the line, circling — left NA |
| after 5 end | the line is over — left NA |
| before any event | unknown — left NA |
Codes 6 and 7 mark a kind of sighting rather than a stage of the line. They are left as recorded and do not change the state carried past them.
So the only code ever written is 2, and only where the line is genuinely
continuing. A record before the first event, during a circle, or after the
line closed keeps its NA and stays ineligible — which is correct, because
a detection made while not searching the line breaks the distance-sampling
assumptions rather than merely the bookkeeping.
What it is for
on_effort_census_rows() requires LEGSTAGE == 2, and handbook 8.A.31
restricts a right-angle distance measurement to records in that state. On a
real archive 1,928 of 2,280 on-effort census sightings carried no
LEGSTAGE, so 85% of the detections that could have informed a detection
function were excluded for a code nobody wrote down.
References
Kenney, R.D. (2023) The North Atlantic Right Whale Consortium Database: A Guide for Users and Contributors, Version 8, sections 8.A.20 and 8.A.31. NARWC Reference Document 2023-01.
See also
on_effort_census_rows(), which is what this makes answerable;
fill_narwc() for columns whose value carries forward.
Examples
dat <- data.frame(
FILEID = "F", EVENTNO = 1:6, LEGNO3 = "1_1", LEGTYPE = 2,
LEGSTAGE = c(1, NA, NA, 5, NA, NA)
)
fill_legstage(dat, quiet = TRUE)$LEGSTAGE
#> [1] 1 2 2 5 NA NA