Skip to contents

Runs 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 criterion flag_effort() needs; a number takes that many days from the start; a Date or 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(). Default 10.

species

Passed to segment_survey(). Default NULL.

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 to segment_survey(). See platform_defaults().

...

Passed to read_narwc() when x is a path: profile, extra_columns, prefer_source and 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.