Read and standardize North Atlantic Right Whale Consortium (NARWC) survey data.
narwcr is the common data preparation layer beneath analysis packages that read the same archive but diverge in their modelling methods. It does the part that is the same for everyone — getting a NARWC extract into a single, predictable shape — and nothing that is specific to any one analysis.
read_narwc() |
read an extract, matching column names loosely |
standardize_narwc_columns() |
apply the shared vocabulary to a table you already have |
narwc_column_mapping() |
the full dictionary of what was renamed to what |
fill_narwc() |
fill the fields the archive records once per leg, not once per row |
narwc_fill_columns(), narwc_never_fill()
|
which columns may be filled, and which must never be |
validate_narwc() |
check a table against the handbook’s own rules |
narwc_checks() |
the handbook-general check set, extensible by the caller |
narwc_codes(), narwc_schema(), narwc_strip_bins()
|
the handbook code books |
narwc_profiles() |
how named survey programmes differ from each other |
flag_effort(), visibility_ok(), make_leg_id()
|
on-effort records and leg identity |
fill_legstage() |
reconstruct the line state on records that record no LEGSTAGE
|
angles_from_declination() |
split one declination column and a side into ANGLEL/ANGLER
|
track_speed(), classify_platform()
|
how fast the platform was moving, and what it therefore was |
narwc_fetch(), narwc_cloud_roots()
|
fetch extracts from cloud storage |
run_narwc_app() |
look at an extract on an interactive map |
Column standardization
Different survey programs sometimes use different names to record the same data, and occasionally the same name for different quantities. read_narwc() matches loosely and prints in the console exactly how the names were updated. Matches that are guesses are reported as such.
dat <- read_narwc("extract.csv")
narwc_column_mapping(dat)Where a file records data with no corresponding column in the Kenney Handbook, it must be named explicitly in the function callrather than guessed:
dat <- read_narwc("extract.csv",
extra_columns = c("Decl_Angle", "Left_or_Right"))
dat <- angles_from_declination(dat, "Decl_Angle", "Left_or_Right")In the handbook, PLATFORM is optional. Since a data extract can hold both aerial and vessel surveys with no differentiator and the distance machinery downstream is not platform-agnostic, platform needs to be classified.
legs$kind <- classify_platform(legs) # aerial, vessel, stationaryA survey aircraft flies at 90–120 knots and a survey vessel makes about 10.
Map app to check the data platform before performing analysis
run_narwc_app(dat) # or a path, or nothing at all
run_narwc_app(dat, pam = "detections.csv") # with the acoustic record beside itAn interactive map of the extract: where the platform went, what it saw, and when. Aerial, vessel and opportunistic records are told apart by LEGTYPE (handbook 8.A.21) and, where LEGTYPE says nothing, by how fast the platform was moving — and the app reports which records were read and which were inferred, because those are not the same claim. Passive acoustic monitoring is not in the sightings archive and comes from its own file, drawn as stations with recording effort as the denominator.
flag_effort()’s criteria are controls rather than constants. Moving the Beaufort cutoff and watching the on-effort track shrink is the fastest way to see what a threshold costs.
Validation
validate_narwc() runs the handbook-general checks by default. Packages built on top add their own without narwcr needing to know what they are:
validate_narwc(dat) # handbook rules only
validate_narwc(dat, checks = c(narwc_checks(), my_checks()))Installation
# install.packages("pak")
pak::pak("chross22/narwcr")