R/imos_smru_dm_qc.R
imos_smru_dm_qc.RdRuns the whole delayed-mode (DM) QC of one IMOS SMRU tag campaign (seals or turtles) and records it:
writes, or checks and updates, the campaign config file;
suggests track end dates with smru_suggest_trim() and opens the review
PDF;
asks the operator to accept, edit or reject the suggested end dates;
runs smru_qc();
zips the output .csv files;
uploads the zip file to AODN by sftp, after the operator confirms.
imos_smru_dm_qc(
cid,
wd,
config = NULL,
meta.file = NULL,
species = NULL,
common_name = NULL,
release_site = NULL,
state_country = NULL,
dropIDs = NULL,
build.meta = NULL,
model.args = list(),
smru.usr = NULL,
smru.pwd = NULL,
p2mdbtools = "/opt/homebrew/Cellar/mdbtools/1.0.1/bin/",
download = NULL,
review = TRUE,
upload = TRUE,
aodn.user = "",
aodn.path = "/data/IMOS/AATAMS/ANIMAL_TRACKING_SATTAG_QC/dm/",
...
)the SMRU campaign id, e.g. "ct155"
the working directory for the campaign's DM QC
the config file name (relative to wd) or path. Default:
config_<cid>.json
the IMOS metadata .csv file. If NULL, the file named in
an existing config file is used. Delayed-mode QC requires a metadata file:
the function stops if there is none. It also stops if the file has no
deployments for cid, unless build.meta = TRUE. Each deployment's ptt,
body, WMO ID and tag type are checked against the SMRU data server, whose
values are used where they differ; the QC stops if the server cannot be
reached. Set "server.check": false in the config setup block to skip the
SMRU server check for one campaign: ptt, body, WMO ID and tag type are then
taken from the metadata file unchecked, and build.meta must be false
the species scientific name. Required only if it cannot be
read from meta.file or an existing config file
the species common name. Default: from the species lookup table
the release site. Default: the metadata Location, or
the existing config value
the country or territory of the release site. Default: from the release site lookup table
a .csv file of deployments to exclude from the QC. Default:
the existing config value, or an existing <cid>_dropIDs.csv in wd.
Deployments are QC'd whether or not they have a WMO ID
logical; QC deployments that are in the tag data but not
in the metadata file, with metadata built from the SMRU data server (ptt,
body, WMO ID, tag type), the Argos locations (release date and position,
after any pre-deployment test transmissions), the .mdb deployments table
LOCATION (release site, used if within 50 km of the estimated release
position; otherwise a known site within 10 km of the daily median
position on any of the first 7 days; otherwise the nearest known site
within 50 km, or the config meta release site within 50 km) and the config meta block (species). The built
metadata are listed for confirmation and recorded in
qc/diag/<cid>_built_metadata.csv. NULL (default) uses "build.meta"
in the config setup block (false if absent)
a named list of model settings that replace the
species defaults or the existing config values, e.g. list(dist = 50)
the SMRU data server login. Required for a new config file
the path to the mdbtools binaries, used for a new config file
logical; download the campaign .mdb file from the SMRU
server before the QC, replacing the local copy. NULL (default) uses
"download" in the config file (false for a new config file). The .mdb
file is always downloaded if there is no local copy. It is downloaded once
per run, so the trim review and the QC use the same data
logical; review the suggested track end dates interactively
(TRUE), or use the trimIDs file set in the config file (FALSE)
logical; offer to upload the zip file to AODN. The upload always needs confirmation in an interactive session
the AODN sftp username. If blank, it is asked for at upload time
the AODN sftp directory for DM QC files
further arguments passed to smru_suggest_trim()
invisibly, a list with the config file path, the trimIDs file
path (or NULL), the zip file path, whether the upload succeeded, and the
value returned by smru_qc()
Config file. If config exists, it is read and these settings are applied:
"QCmode": "dm"; "diag.dir": "qc/diag"; for Weddell seals,
"time.step": 6 and "min.gap": 48; the meta section derived as below;
and any meta.file, dropIDs, smru.usr, smru.pwd, download and
model.args supplied. Every change is listed and must be confirmed before
the file is rewritten. If config does not exist, it is built from the
species defaults and the arguments.
The meta section. species and release_site are taken, in order of
precedence, from the arguments, from the IMOS metadata file (the Species
and Location of the campaign's deployments) and from the existing config
file. common_name comes from the argument or else from the species
lookup table. state_country comes from the argument or else from the
release site lookup table. With a metadata file, release_site lists every
site of the campaign, most common first, joined by "; ", and
state_country lists their states or countries the same way. These
entries are a record only: the output metadata take the release site, state
or country, and species of each deployment from the metadata file.
species (the most common) still selects the model settings.
Track truncation review (review = TRUE). The choices are:
accept all suggested end dates (accept_trim_dates());
edit <cid>_trimIDs_draft.csv, save it, then continue
(accept_trim_dates() checks it and copies it to <cid>_trimIDs.csv);
use an existing <cid>_trimIDs.csv unchanged;
truncate no tracks;
stop.
With review = FALSE, the trimIDs file already set in the config file is
used, or no track is truncated if none is set. Use it to repeat a run with
the recorded config file and track truncation file.
Records. Each run writes:
the config file as used;
<cid>_trimIDs.csv (if any track is truncated);
qc/diag/<cid>_dm_log.txt, appended on each run, with the ArgosQC and
aniMotum versions (and git commits where available), the review
decision, the files zipped and the sftp outcome.
if (FALSE) { # \dontrun{
## first run: review the suggested track end dates interactively
imos_smru_dm_qc(cid = "ct155",
wd = "/Volumes/work/R/imos/imos_sat/seals/past_qc/dm_qc",
aodn.user = "user@example.org")
## repeat a run with the recorded config and track truncation files
imos_smru_dm_qc(cid = "ct155",
wd = "/Volumes/work/R/imos/imos_sat/seals/past_qc/dm_qc",
review = FALSE)
} # }