Package 'ArgosQC'

the final aniMotum fit object from QC process

the initial aniMotum fit object from QC process

the SSM-estimated or rerouted locations to be used

logical; should predicted locations be dropped if keep = FALSE - ie. in a large data gap

the standardized WC Locations or SMRU diag file (prior to truncation by metadata CTD start and end dates)

the ssm-annotated WC/SMRU tables

metadata

add track lines to map (default = FALSE)

add observed locations to map (default = FALSE)

path to write map file

path to write all other diagnostic files

specify whether QC is near real-time (nrt) or delayed-mode (dm), in latter case start end end of dive data are displayed rather than ctd data.

the tag manufacturer. Currently, only smru or wc are supported.

SMRU campaign id (from config file). Ignored if WC data is used.

destination path to save download

source type of data to be downloaded. Can be one of:

• smru - SMRU Data Server;

• wc - Wildlife Computers Data Portal API;

SMRU tag deployment campaign id(s) to download, eg. "ct180"

SMRU data server username as a quoted string

SMRU data server password as a quoted string

an Access Key issued by Wildlife Computers for their API

a Secret Key issued by Wildlife Computers for their API

the Wildlife Computers uuid associated with the data owner

a single column .CSV file of WC UUID's to be included in the QC, with uuid as the variable name.

(logical) indicating if the data is to be downloaded from the tag manufacturer's server. If the source is wc and download = FALSE then only the Wildlife Computers tag deployment metadata is downloaded.

additional arguments passed to smru_get_mdb() or wc_get_files()

the source of the deployment metadata, current options are imos, smru, or atn. If source = 'imos' or source = 'atn' then metadata are obtained from user-provided .CSV file via the config.json file. If sourcce = 'smru' then metadata are built from a combination of SMRU server details & deployment details in the config.json file.

the tag manufacturer, current options are smru or wc cid SMRU campaign ids

a list of either smru data tables or wc files as output by pull_data.

SMRU campaign id must be provided when the tag_mfr is smru

SMRU data server username as a quoted string - to be used only if metadata are to be built from SMRU server details (source = 'smru').

SMRU data server password as a quoted string - to be used only if metadata are to be built from SMRU server details (source = 'smru').

SMRU refs or WC ids to be dropped from QC

path to metadata .csv file, if provided then metadata will be read from the provided source

optional metadata fields to be passed from config file when downloading tag metadata from SMRU server. Typically used only when no metadata filepath is provided in the config file.

a character vector of comma-separated (no spaces) WC UUID's to be included in the QC. Ignored if tag_mfr != "wc".

an R data.frame of Wildlife Computers tag deployment metadata obtained via download_data(). Typically used only when no metadata filepath is provided in the config file.

a aniMotum ssm fit object with class ssm_df or (old) fG_ssm

optionally, a aniMotum mpm fit object with class mpm_df or (old) fG_mpm

specify which location estimates to map: fitted, predicted or rerouted

a list of map controls and aesthetics (shape, size, col, fill, alpha) for each map feature (estimated locations, confidence ellipses, track lines, observed locations, land masses, water bodies). Constructed by aes_lst() and can be modified for custom maps (see examples)

when mapping multiple tracks, should locations be coloured by id (logical; default = TRUE if nrow(x) > 1 else FALSE; ignored if behavioural index provided)

when mapping single tracks, should locations be coloured by date (logical; default = FALSE; ignored if behavioural index provided)

logical; should predicted locations be dropped from mapping if keep = FALSE. default = FALSE.

proj4string for re-projecting locations, if NULL the default projection (Mercator) for the fitting the SSM will be used

proportion (can exceed 1) to extend the plot range in x and y dimensions

distance (in km) to buffer locations for subsetting land polygons (default = 10000). If map extents are expanded by many factors then the buffer distance may need to be increased, otherwise this should not be used. Ignored if map_type != "default".

logical; if output includes a move persistence estimate, should g (the move persistence index) be normalised to have minimum = 0 and maximum = 1 (default = TRUE).

logical; should g be normalised among individuals as a group, a 'relative g', or separately to highlight regions of lowest and highest move persistence along a track (default = FALSE).

logical; generate maps silently (default = FALSE).

sf-projected diag file of locations to be filtered

for prefilter

aniMotum model ("rw" orr "crw)

foieGrsa time.step

turn on/off furrr::future_map progress indicator

path to local datafile(s)

SMRU campaign id. Ignored if tag_mfr = "wc".

either "smru" or "wc"

aniMotum fit object from first round of filtering

sf-projected diag to be used

model argument ("rw" or "crw) for aniMotum::fit_ssm

time.step argument for aniMotum::fit_ssm

threshold travel speed (m/s) to apply during track pre-filtering

sdafilter argument

sdafilter argument

min.dt argument for aniMotum::fit_ssm

params to fix

(logical) should SSM-predicted locations be re-routed off of land (default is TRUE)

the distance (in km) to buffer around predicted locations. This buffer allows a larger portion of coastline to be selected for rerouting any locations that are on land. More coastline polygon data can help rerouting, but too much will make computation very slow.

add a custom POLYGON/MULTIPOLYGON shapefile to use as a land barrier. Default (NULL) reverts to the aniMotum default land barrier.

turn on/off furrr::future_map progress indicator

additional arguments to aniMotum::route_path

SMRU table file - output of pull_smru_tables

final foieGras fit object

choose which locations to use for annotating SMRU tables (default = "predicted")

metadata used to truncate start of diag data for each individual

drop predicted locations if keep = FALSE, ie. locations in a large data gap

SMRU refs to be dropped

list of SMRU tables

SMRU refs to be dropped (eg. tags were turned on but not deployed)

list of SMRU tables

metadata used to truncate start of diag data for each individual

SMRU refs to be dropped (eg. tags were turned on but not deployed)

a proj4string to re-project diag locations from longlat. Default is NULL which results in one of 4 possible projections applied automatically, based on the centroid of the tracks. See overview vignette for details.

specify whether QC is near real-time (nrt) or delayed-mode (dm), in latter case diag is not right-truncated & date of first dive is used for the track start date

SMRU campaign ids

path to SMRU .mdb file(s)

specify which tables to extract, default is to extract all tables

path to mdbtools binaries. Specifying the path can avoid an error when calling from within RStudio, eg. on MacBook Pro M1 Pro with homebrew-installed mdbtools @ /opt/homebrew/Cellar/mdbtools/1.0.0/bin/

turn on/off progress indicator

the path to the working directory that contains: 1) the data directory where tag data files are stored (if harvest$download = FALSE) or downloaded to (if harvest$download = TRUE); 2) the metadata directory where all metadata files are stored; and 3) the destination directory for QC outputs.

a hierarchical JSON configuration file containing the following blocks, each with a set of block-specific parameters:

• setup config block specifies paths to required data, metadata & output directories:

  • program the national (or other) program of which the data is a part. Current options are: imos, atn, or otn.

  • data.dir the name of the data directory. Must reside within the wd.

  • meta.file the metadata filename. Must reside within the wd. Can be NULL, in which case, the meta config block (see below) must be present & tag-specific metadata are scraped from the SMRU data server.

  • maps.dir the directory path to write diagnostic maps of QC'd tracks.

  • diag.dir the directory path to write diagnostic time-series plots of QC'd lon & lat.

  • output.dir the directory path to write QC output CSV files. Must reside within the wd.

  • return.R logical; should the function return a list of QC-generated objects to the R works pace. This results in a single large object containing the following elements:

    • cid the SMRU campaign ID

    • dropIDs the SMRU Reference ID's droppped from the QC process

    • smru the SMRU tag data tables extracted from the downloaded .mdb file

    • meta the working metadata

    • locs_sf the projected location data to be passed as input to the SSM

    • fit1 the initial SSM output fit object

    • fit2 the final SSM output fit object including re-routed locations if specified.

    • smru_ssm the SSM-annotated SMRU tag data tables. This output object can be useful for troubleshooting undesirable results during supervised or delayed-mode QC workflows.

• harvest config block specifies data harvesting parameters:

  • download a logical indicating whether tag data are to be downloaded from the SMRU data server or read from the local data.dir.

  • cid SMRU campaign ID.

  • smru.usr SMRU data server username as a string.

  • smru.pwd SMRU data server password as a string.

  • timeout extends the download timeout period a specified number of seconds for slower internet connections.

  • dropIDs the SMRU ref ID's that are to be ignored during the QC process. SMRU ref ID's must be supplied as a .CSV file dropIDs.csv with a single variable named ref. Can be NULL.

  • p2mdbtools (optional) provides the path to the mdbtools library if it is installed in a non-standard location (e.g., on Macs when installed via Homebrew).

• model config block specifies model- and data-specific parameters:

  • model the aniMotum SSM model to be used for the location QC - typically either rw or crw.

  • vmax for SSM fitting; max travel rate (m/s) to identify implausible locations

  • time.step the prediction interval (in decimal hours) to be used by the SSM

  • proj the proj4string to be used for the location data & for the SSM-estimated locations. Can be NULL, which will result in one of 5 projections being used, depending on whether the centroid of the observed latitudes lies in N or S polar regions, temperate or equatorial regions, or if tracks straddle (or lie close to) -180,180 longitude.

  • reroute a logical; whether QC'd tracks should be re-routed off of land (default is FALSE). Note, in some circumstances this can substantially increase processing time. Default land polygon data are sourced from the ropensci/rnaturalearthhires R package.

  • dist the distance in km from outside the convex hull of observed locations from which to select land polygon data for re-routing. Ignored if reroute = FALSE.

  • barrier the file path (must be within the working directory) for a shapefile to use for the land barrier. If NULL (default) then the default rnaturalearth coastline polygon data is used.

  • buffer the distance in km to buffer rerouted locations from the coastline. Ignored if reroute = FALSE.

  • centroids whether centroids are to be included in the visibility graph mesh used by the rerouting algorithm. See ?pathroutr::prt_visgraph for details. Ignored if reroute = FALSE.

  • cut logical; should predicted locations be dropped if they lie within in a large data gap (default is FALSE).

  • min.gap the minimum data gap duration (h) to be used for cutting predicted locations (default is 72 h)

  • QCmode one of either nrt for Near Real-Time QC or dm for Delayed Mode QC.

• meta config block specifies species and deployment location information. This config block is only necessary when no metadata file is provided in the setup config block.

  • common_name the species common name (e.g., "southern elephant seal")

  • species the species scientific name (e.g., "Mirounga leonina")

  • release_site the location where tags were deployed (e.g., "Iles Kerguelen")

  • state_country the country/territory name (e.g., "French Overseas Territory")

SSM-appended SMRU file to use

metadata used to truncate SSM-appended SMRU tables for each individual

device_id's (SMRU ref's) to apply truncation

SSM-appended SMRU table file - output of append_ssm

final aniMotum fit object

specify whether predicted or rerouted locations are to be used

metadata

Determines structure of output metadata. The imos & atn programs have their own defined metadata structures, all other programs are treated as "Generic".

the proj4string specified in the .JSON config file & used to project the location data prior to SSM fitting. It is passed in here to be added to the output metadata .CSV file

should variables be tested for standards compliance, default is TRUE. Standards compliance is specific to the program. Currently, only program = imos has defined variable standard against which output compliance is tested.

path to write .csv files

individual SMRU ids to be dropped

suffix to add to .csv files (_nrt, _dm, or _hist)

the SSM fit object from redo_multi_filter()

the minimum data gap duration from which SSM estimates are removed (in hours)

logical; should the SSM data be marked (TRUE; default), otherwise the function does no marking and returns the original SSM fit object

WC tag datafiles - output of pull_wc

final aniMotum fit object(s)

choose which locations to use for annotating WC tag datafiles (default = "predicted")

metadata used to truncate start of diag data for each individual

drop predicted locations if keep = FALSE, ie. locations in a large data gap (currently, only used in DM QC mode)

SMRU DeploymentIDs to be dropped

CRS to be applied when interpolating SSM-estimated locations and re-projecting back from Cartesian coords to longlat

list of WC datafiles

metadata used to truncate start of diag data for each individual

WC DeploymentID's to be dropped (eg. tags were turned on but not deployed)

a proj4string to re-project diag locations from longlat. Default is NULL which results in one of 4 possible projections applied automatically, based on the centroid of the tracks. See overview vignette for details.

specify the aniBOS program contributing data (currently: 'atn', 'irap')

specify whether QC is near real-time (nrt) or delayed-mode (dm), in latter case wc is not right-truncated & date of first dive is used for the track start date.

path to all WC tag data files.

a single column .CSV file of WC UUID's to be included in the QC, with uuid as the variable name.

the path to the working directory that contains: 1) the data directory where tag data files are stored (if source = local); 2) the metadata directory where all metadata files are stored; and 3) the destination directory for QC output.

a hierarchical JSON configuration file containing the following blocks, each with a set of block-specific parameters:

• setup config block specifies paths to required data, metadata & output directories:

  • program the national (or other) program of which the data is a part. Current options are: atn, or irap.

  • data.dir the name of the data directory. Must reside within the wd.

  • meta.file the metadata filename. Must reside within the wd. Can be NULL, in which case, the meta config block (see below) must be present & tag-specific metadata are scraped from the SMRU data server.

  • maps.dir the directory path to write diagnostic maps of QC'd tracks.

  • diag.dir the directory path to write diagnostic time-series plots of QC'd lon & lat.

  • output.dir the directory path to write QC output CSV files. Must reside within the wd.

  • return.R logical; should the function return a list of QC-generated objects to the R works pace. This results in a single large object containing the following elements:

    • cid the SMRU campaign ID

    • dropIDs the SMRU Reference ID's droppped from the QC process

    • smru the SMRU tag data tables extracted from the downloaded .mdb file

    • meta the working metadata

    • locs_sf the projected location data to be passed as input to the SSM

    • fit1 the initial SSM output fit object

    • fit2 the final SSM output fit object including re-routed locations if specified.

    • smru_ssm the SSM-annotated SMRU tag data tables. This output object can be useful for troubleshooting undesirable results during supervised or delayed-mode QC workflows.

• harvest config block specifies data harvesting parameters:

  • download a logical indicating whether tag data are to be downloaded from the WC data portal (TRUE) or read from the local data.dir (FALSE).

  • collab.id (optional) the WC data owner ID associated with the data to be downloaded. Ignored (if provided) when harvest$download:FALSE.

  • wc.akey (optional) the WC access key for API access to the data portal. Ignored (if provided) when harvest$download:FALSE.

  • wc.skey (optional) the WC secret key for API access to the data portal. Ignored (if provided) when harvest$download:FALSE.

  • dropIDs the WC UUID(s) for specific tag data set(s) that is/are to be ignored during the QC process. UUID's are supplied as a .CSV file dropIDs.csv with a single variable named uuid. Can be NULL.

• model config block specifies model- and data-specific parameters:

  • model the aniMotum SSM model to be used for the location QC - typically either rw or crw.

  • vmax for SSM fitting; max travel rate (m/s) to identify implausible locations

  • time.step the prediction interval (in decimal hours) to be used by the SSM

  • proj the proj4string to be used for the location data & for the SSM-estimated locations. Can be NULL, which will result in one of 5 projections being used, depending on whether the centroid of the observed latitudes lies in N or S polar regions, temperate or equatorial regions, or if tracks straddle (or lie close to) -180,180 longitude.

  • reroute a logical; whether QC'd tracks should be re-routed off of land (default is FALSE). Note, in some circumstances this can substantially increase processing time. Default land polygon data are sourced from the ropensci/rnaturalearthhires R package.

  • dist the distance in km from outside the convex hull of observed locations from which to select land polygon data for re-routing. Ignored if reroute = FALSE.

  • barrier the file path (must be within the working directory) for a shapefile to use for the land barrier. If NULL (default) then the default rnaturalearth coastline polygon data is used.

  • buffer the distance in km to buffer rerouted locations from the coastline. Ignored if reroute = FALSE.

  • centroids whether centroids are to be included in the visibility graph mesh used by the rerouting algorithm. See ?pathroutr::prt_visgraph for details. Ignored if reroute = FALSE.

  • cut logical; should predicted locations be dropped if they lie within in a large data gap (default is FALSE).

  • min.gap the minimum data gap duration (h) to be used for cutting predicted locations (default is 72 h)

  • QCmode one of either nrt for Near Real-Time QC or dm for Delayed Mode QC.

  • pred.int the prediction interval (h) to use for sub-sampling predicted locations prior to interpolation of QC'd locations to tag data file event times.

SSM-appended WC tag datafiles - output of append_wc_ssm

final SSM fit object

specify whether predicted or rerouted locations are to be used

metadata

Determines structure of output metadata. Currently, either imos or atn.

path to write .csv files

individual WC DeploymentID's to be dropped

suffix to add to .csv files (_nrt, _dm, or _hist)

prediction interval to use for sub-sampling predicted locations (default = 6 h)