Diagnose common reasons a segmentation might be wrong before you trust it
Source:R/diagnose.R
diagnose_pipeline.RdRuns the reading and segmentation pipeline (read_narwc(),
validate_narwc(), make_leg_id(), flag_effort(),
point_to_point_effort() and segment_survey()) and reports the ways a
real extract goes wrong quietly. Run it once against a new dataset, before
any of its numbers are used.
Usage
diagnose_pipeline(
x,
days = NULL,
seg_length = 10,
species = NULL,
platform = c("aerial", "vessel", "ship"),
...
)Arguments
- x
A path to a NARWC CSV, or a data frame. A path is read with
read_narwc(); a data frame is taken as already read.- days
Which survey days to diagnose, so a large extract can be checked in seconds before it is run in full.
"auto"picks the day with the most census records carrying every criterionflag_effort()needs; a number takes that many days from the start; aDateor date string takes exactly those days.NULL(default) uses everything."auto"is the recommended choice. The start of a season is often atypical: a day may lack the altitude or sea state the rest of the file records. Every criterion fails on a missing value, so an unrepresentative day reports no effort at all while the file is fine.Whole days are kept, never a sample of records. Effort and segmentation are computed from consecutive positions along a line, so a random subset of records would report distances across gaps created by the sampling. Every total printed is for the subset, and the header says so.
- seg_length
Segment length in km, passed to
segment_survey(). Default10.- species
Passed to
segment_survey(). DefaultNULL.- platform
"aerial"(default),"vessel", or"ship"as a synonym for"vessel". The platform the file is believed to hold. Every check that depends on it (the altitude ceiling, the expected speed, which distance sources can exist) uses this, and it is passed on tosegment_survey(). Seeplatform_defaults().- ...
Passed to
read_narwc()whenxis a path:profile,extra_columns,prefer_sourceand so on.
Value
Invisibly, a list with whichever of dat, findings and segments
the checks reached before a fatal problem stopped them, so investigating
can carry on from there.
Details
The target is not the failure that errors. It is the failure that returns a plausible number: effort that silently includes the ferry between two survey days, an altitude read as metres when the column was in feet, a position taken from the vessel when the aircraft's GPS track was in the file. Each gives a density estimate that is wrong by a factor and looks reasonable.
Every check reports rather than fixes. This function never modifies the data or the arguments it was given.
See also
validate_narwc() for the per-record checks this summarises,
line_effort() and reflight_summary() for the per-line detail behind
the effort totals, and plot() on the result of segment_survey().
Examples
path <- system.file("extdata", "narwc-example.csv", package = "distsamp")
invisible(diagnose_pipeline(path, seg_length = 5))
#> distsamp pipeline diagnosis, as a aerial survey
#>
#> == Reading ==
#> ok 113 records, 30 columns
#>
#> == Handbook validation ==
#> ok legstage_line_not_closed (1 records): A line occupation has no end-line (LEGSTAGE 5). This is normal for a line abandoned mid-flight - for weather, or to re-fly it later - and a problem only if the line was flown to completion.
#>
#> == Platform ==
#> ok 1 distinct PLATFORM value(s): 210 x 113
#>
#> == Line identity ==
#> ok 6 line occupation(s) over 2 survey day(s), 5 record(s) on no line
#>
#> == Altitude ==
#> ok median ALT 229 m
#>
#> == Effort ==
#> off effort by criterion (defaults; a record can fail more than one):
#> BEAUFORT above 3: 2
#> LEGTYPE not 2: 10
#> ok 101 of 113 records on effort
#> ok 92.2 km of on-effort track
#> ok grouping without DATE gives the same total; no days are merging
#> ok median speed 86 knots, consistent with a survey aircraft
#>
#> == Right-angle distance sources ==
#> ok 14 sighting record(s)
#> ok 9 with a declination angle
#> ok 4 with an exact position
#> ok 9 with a strip code
#>
#> == Segments ==
#> ok 20 segment(s) at seg_length = 5 km
#> ok every segment carries effort
#>
#> Nothing above needs attention.