--- title: "SMRU_config_file" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{SMRU_config_file} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} editor_options: markdown: wrap: 72 --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## SMRU QC config file structure All ArgosQC workflows are structured using a JSON config file. The config file is hierarchical in structure with as many as 4 blocks: `setup`, `harvest`, `model`, and `meta`. The `meta` block is only required if no metadata file is provided in the `setup` block. These files can be constructed manually or programmatically and provide the ability to define certain aspects of the QC workflow. Below is the config file for an IMOS QC workflow on SMRU GPS SRDL-CTD tags deployed on olive ridley turtles on the Tiwi Islands, Australia. All SMRU tag data are organised by deployment campaign ids, e.g., `ct188`. A separate QC workflow (config file) must be generated for each deployment campaign.
![](images/IMOS_config_JSON.png){width="100%"}
The block-specific parameters are as follows: With a completed config file, the standard call to initiate the QC workflow within R is: ```{r fn call, eval=FALSE} smru_qc(wd = "test", config = "imos_config.json") ``` where `wd` is the file path for the working directory within which all QC data/metadata inputs are downloaded (or read) and outputs are written. ### Additional details on config parameters The `proj` argument specifies the projection (as a `proj4string`) to which the tag-measured locations are converted as input to the QC state-space model (SSM), ie. the working projection in `km` for the SSM. Any valid `proj4string` may be used, provided the units are in `km`. If `proj` is left as `NULL` then the QC algorithm will project the data differently depending on the centroid latitude of the tracks. The default projections are: | Central Latitude or Longitude | Projection (with `+units=km`) | |:-----------------:|:---------------------------------------------------:| | -55 to -25 or 25 to 55 Lat | Equidistant Conic with standard parallels at the tracks' 25th & 75 percentile Latitudes | | \< -55 or \> 55 Lat | Stereographic with origin at the tracks' centroid | | -25 to 25 Lat | Mercator with origin at the tracks' centroid | | -25 to 25 Lat & Long straddles -180,180 | Longitudes are shifted to 0, 360 and a Mercator with origin at tracks' centroid | The `model` argument specifies the `aniMotum` SSM to be used; typically either `rw` or `crw`. The latter is usually less biased when data gaps are absent, the former is best when data gaps are present. A general recommendation is to use `model`:`rw` as the SSM for unsupervised (e.g., NRT) QC workflows. The SSM fitting algorithm has a few fundamental parameters that need to be specified; `vmax` is the animals' maximum plausible travel rate in ms$^{-1}$. For example, `vmax`:`3` is usually appropriate for seals and `vmax`:`2` for turtles. The SSM prediction interval in hours is specified with `time.step`. Decimal hours can be used for `time.steps` shorter than 1 hr. This time interval determines the temporal resolution of the predicted track. The predicted track locations provide the basis for interpolation to the time of each tag-measured ocean observation or behavioural event. Typically, 6 hours is appropriate for most Argos data collected from seals and turtles but a finer time interval may be required for faster moving species and/or more frequently measured ocean observations, and a coarser interval for more sporadically observed locations. Further details on SSM fitting to Argos and GPS data are provided in the associated R package [aniMotum vignettes](https://ianjonsen.github.io/aniMotum/) and in [Jonsen et al. 2023](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.14060). When animals pass close to land some SSM-predicted locations may implausibly lie on land. Often, this is due to the spatial and temporal resolution of the Argos tracking data. In these cases, SSM-predicted locations can be adjusted minimally off of land by setting `reroute`:`true`. The [`pathroutr` R package](https://jmlondon.github.io/pathroutr/) is used for efficient rerouting. In this case, additional arguments should be specified: `dist` - the distance in km beyond track locations from which coastline polygon data should be sampled (smaller provides less information for path re-routing, greater increase computation time) `barrier` - an optional parameter that can provide an alternate spatial polygon dataset , as a shapefile, for the land (or other barriers to movement). Typically, this alternate dataset would be a localised, high-resolution coastline dataset. `buffer` - the distance in km to buffer rerouted locations from the coastline `centroid`- whether to include the visibility graph centroids for greater resolution SSM-predicted tracks can be `cut` (`cut`:`true`) in regions where large location data gaps exist. These location data gaps can occur when the tags are unable to transmit for extended periods or when animal surfacing occurs during periods of Argos satellite unavailability (more common closer to the equator than at higher latitudes). In this case, `min.gap` is used to specify the minimum data gap duration (h) from which to cut SSM-predicted locations. This will limit interpolation artefacts due to implausible SSM-predicted locations in excessively long data gap periods. The `QCmode` sets whether the QC is being conducted in delayed-mode `dm` or near real-time `nrt`. Delayed-mode is reserved for when tag deployments have ended and usually involve greater user intervention; such as making decisions on removing aberrant portions of a deployment (e.g., as tag batteries begin failing). The `nrt` mode is mean to be fully automated and only used while a deployment is active. In both cases, the output .CSV and plot file names will include the `QCmode` as a suffix.