R/smru_suggest_trim.R
smru_suggest_trim.RdReads a campaign's SMRU tag data and deployment metadata, as
smru_qc() does, but fits no SSM. For each deployment it suggests an
end_date for truncating the track, writes the suggestions to a draft .csv
file for review, and writes a review PDF with one page per deployment: the
whole track beside a zoom on the end of the track. After review, the file is
supplied to smru_qc() through the trimIDs entry of the config file.
The function runs only for delayed-mode QC (QCmode = "dm"). Near real-time
QC is unsupervised, so no tracks are truncated there.
smru_suggest_trim(
wd,
config,
draft_file = NULL,
plot_file = NULL,
min_post_days = 2,
stationary_radius_km = 30,
min_stationary_days = 2,
sparse_mean = 10,
very_sparse_daily = 5,
final_haulout_days = 2,
min_final_haulout_hours = 6,
haulout_reversal_days = 5,
final_gap_days = 7,
final_gap_max_days = 3,
final_outlier_km = 500,
final_outlier_days = 2,
keep_days = 0,
plots = TRUE
)the working directory, as in smru_qc()
the JSON config file, as in smru_qc(). QCmode must be "dm"
path for the draft truncation file. Default:
<cid>_trimIDs_draft.csv in wd
path for the review PDF. Default: trim_review_<cid>.pdf in
the config's diag.dir. Use plots = FALSE to skip the plots
minimum days of locations after the anchor for rules 2 and 3
largest distance (km) of a daily median position from the median position of the final run of days (rule 2)
minimum length (days) of the final stationary run (rule 2)
centred 3-day mean number of locations per day below which a day counts as sparse (rule 3)
a sparse final run must include a day with fewer locations than this (rule 3)
a haul-out beginning within this many days of the last location can set a candidate at its start (rule 5)
minimum length (hours) of that haul-out (rule 5); shorter dry periods are not treated as a final haul-out
if the anchor follows the start of the final haul-out by no more than this many days, the haul-out candidate is replaced by the point just after the anchor (rule 5)
gap between locations, in days, that can end the located track (rule 6)
the longest span of locations after a final gap, in days, for rule 6 to apply
distance (km) from the median end-of-track position beyond which a location is a final outlier (rule 7)
length (days) of the end-of-track window searched for final outliers (rule 7)
days added to each suggested end_date from rules 2 and 3
logical; write the review PDF
invisibly, a data frame with one row per deployment: ref,
start_date (empty), end_date (the suggestion, or empty), rule,
anchor, anchor_type, last_dive, last_ctd, last_location,
n_records_after_track_end, days_after_anchor, stationary_end,
sparse_end, final_haulout_start, final_gap_start, final_outlier,
n_locations_removed, n_dives_removed, n_ctd_removed. The same table is
written to draft_file. The review data are attached as attribute
plot_data, for trim_zoom().
The rules, applied to each deployment:
The anchor is the last CTD profile, or the last dive for a tag with no
CTD profiles. CTD profiles and dives dated after the end of the located
track (the last location, or the start of a final gap under rule 6) are
ignored: they cannot be located, and may be misdated records. Their number
is reported in n_records_after_track_end. A suggested end_date never
removes a CTD profile (except
under rule 5): it always keeps at least one location more than one SSM time
step (time.step in the config file) after the anchor, so the
SSM-predicted track covers every CTD profile. Dives after the last CTD
profile are not protected; they are often records from a failing sensor.
Stationary end: the final run of days whose daily median positions (all
location classes except Z) after the anchor lie within
stationary_radius_km of the run's median position, lasting at least
min_stationary_days. This is a haul-out, or a likely haul-out with
missing haul-out records. Candidate: 00:00 UTC on the run's first day.
Sparse end: the final run of days whose centred 3-day mean number of
locations is below sparse_mean, provided that run includes a day with
fewer than very_sparse_daily locations. This is the location data
petering out at the end of the track (battery, antenna or other tag
failure). Candidate: 00:00 UTC on the run's first day.
Rules 2 and 3 apply only when there are at least min_post_days of
locations after the anchor. The suggested end_date is the earlier of
their candidates, moved later if needed to satisfy rule 1, then moved later
by keep_days. With neither candidate, the track is kept to its end.
Final haul-out: a haul-out that begins within the last
final_haulout_days of the track and lasts at least
min_final_haulout_hours sets a candidate at its start, even if CTD
profiles follow it. Haul-out records separated by less than 1 hour, with no
dive ending in between, are merged into one haul-out first. If the anchor
(the last CTD profile) comes after the start of that haul-out, and no more
than haulout_reversal_days after it, the haul-out was not final: the
candidate is replaced by the point just after the anchor (rule 1), so the
last CTD profile is kept. The suggested end_date is the earliest
candidate.
Final gap: when the locations after the last gap of more than
final_gap_days span no more than final_gap_max_days and include no
CTD profile, the located track ends at the start of that gap. The rule is
repeated on the remaining track while it applies. CTD profiles and dives
inside or after the gap are ignored for the anchor (rule 1). Candidate: just
after the last location before the gap.
Final outlier: an Argos location of any class, including Z, in the last
final_outlier_days of the track that lies more than final_outlier_km
from the median position of the other locations (all classes except Z) in
that window. A single gross error at the end of a track can pull the SSM
track far away, because the speed filter cannot test the last locations
well. Candidate: the time of the earliest such location, so it and any
later locations are removed. The candidate is used only if it keeps every
CTD profile (rule 1); otherwise the outlier is reported in rule for
review.