Using the FishDiveR app • FishDiveR

The FishDiveR app runs the whole workflow, from importing tags to plotting behaviour clusters, without writing code. It runs in your web browser but entirely on your own computer, so your data never leave your machine.

This vignette explains how the app is organised and what each step does. The methods behind each step are explained in vignette("FishDiveR").

Starting the app

The app needs three extra packages. Install them once:

install.packages(c("shiny", "bslib", "DT"))

Then start the app:

FishDiveR::run_app()

It opens in your web browser. To open a project folder straight away, give its path:

FishDiveR::run_app(project_folder = "C:/Tag data/My project")

To stop the app, close the browser tab and press Esc in the R console (or click the red stop sign in RStudio).

Projects and the folder layout

Everything in the app happens in a project folder. The app saves each step’s results there, in the same layout the FishDiveR functions use when output_folder is the project folder. You can move between the app and R code at any point.

My project/
  tag_metadata.csv        <- the tag table
  237522/                 <- one folder per tag
    archive_days.rds      <- imported depth record
    1_Wavelets/           <- wavelet and its settings
    2_Wavelet_Figures/    <- wavelet spectrum figures
    3_Stats/              <- daily wavelet and depth statistics
  333237/
    ...
  Combined_tags/          <- results for several tags analysed together
    4_PCA/                <- PCA results and figures
    5_k-means/            <- combined data, k-means results and figures
    6_Cluster-plots.K=4/  <- example days of each cluster

When a PCA is run on a single tag, its 4_PCA, 5_k-means and 6_Cluster-plots folders are in that tag’s folder instead of Combined_tags.

The tag table

The tags in a project are listed in a tag table, saved as tag_metadata.csv. You can add tags one at a time in step 1, or load a whole table from a csv file with these columns:

Column	Required	Description
`tag_ID`	Yes	Unique ID of the tag, e.g. `237522`
`archive`	Yes	Path of the tag’s csv archive
`tag_deploy_UTC`	Yes	Deployment time in UTC, `yyyy-mm-dd hh:mm:ss`
`tag_release_UTC`	Yes	Release time in UTC, `yyyy-mm-dd hh:mm:ss`
`time_zone`	Yes	Local time zone, e.g. `Asia/Tokyo` (see `OlsonNames()`)
`date_time_col`	No	Column number of the date-time. Defaults to 1
`depth_col`	No	Column number of the depth. Defaults to 2
`temp_col`	No	Column number of the temperature, if any
`GPS`	No	Path of a GPS csv file (`date`, `lat`, `lon`) for day and night times

For example:

tag_ID,archive,tag_deploy_UTC,tag_release_UTC,time_zone,GPS
237522,D:/Tags/237522-Archive.csv,2023-06-01 04:30:00,2023-06-30 12:00:00,Australia/Perth,D:/Tags/237522-GPS.csv
333237,D:/Tags/333237-Archive.csv,2023-07-02 05:10:00,2023-09-01 08:45:00,Australia/Perth,

Each tag is checked as it is added: that its files exist, its times are in the right format and in order, and its time zone is recognised.

The seven steps

The steps are tabs along the top of the app, in workflow order. The Next button at the bottom right of each step moves on to the next one.

1. Project & tags

Open or create the project folder, then add tags with the form, load a tag table csv, or add the example tag to try things out. Select a tag in the table to edit or remove it. Removing a tag from the table keeps its results in the project folder.

2. Import

Import some or all of the tags. Each archive is cropped to whole local days between deployment and release, and saved in the tag’s folder. The log shows each tag’s messages, including any warning that its sampling interval isn’t constant.

If you change a tag’s archive, deployment or release time, columns or time zone after importing it, the imported record no longer matches its settings. Step 1 warns when you save the tag and in the table’s Check column, and step 2 marks the tag Outdated and lists what changed. Re-import it to use the new settings.

The Sampling column checks each imported tag for a constant sampling interval, e.g. “Regular (5 s)” or “Irregular: 1 duplicate, 2 gaps”. Select a tag to see its full sampling check, from sampling_report(): where any duplicate times, gaps or changes of sampling rate are, and which days have fewer records than expected.

The depth record of any imported tag can then be plotted. Set the points to plot, dates and axes, then click Create plot. Plots of large records can take a while, so the plot only redraws when you click. Fast preview plots the shallowest and deepest record in each of 2,000 time slices, which keeps every dive’s extremes and plots long deployments in about a second. Colour by temperature colours the record from blue (cold) to red (warm), for tags imported with a temperature column.

The Time at depth & temperature tab shows the percentage of time a tag spent in each depth or temperature range, for the whole record, each month, or as a heat map of each day. Leave the range width blank for about 12 ranges of round values, or set your own, e.g. 25 m or 1 °C. Plots can be saved to the tag’s folder.

3. Wavelets

Set the lower period, upper period and sub-octaves, then run the wavelet for selected tags or all tags. The tag table shows each tag’s records, sampling interval and estimated memory, and the settings of any existing wavelet. A warning appears if a selected tag’s wavelet may need more than half of your computer’s memory.

To cut memory and run time, tick Thin records before the wavelet and choose an interval. Select tags in the table to see a suggested interval for them, with the memory it would save; Use this suggestion fills it in. Open How thinning works for a full explanation, and see vignette("large-records", package = "FishDiveR").

The spectrum panel shows each tag’s wavelet power spectrum or mean power by period. Redraw figures redraws them from the saved wavelet without recalculating it.

4. Daily stats

Create the daily wavelet and depth statistics. Diel (day and night) statistics use each tag’s GPS file, or fixed sunrise and sunset times for all tags. The table shows how many days each tag’s statistics cover; the wavelet and depth statistics must cover the same days, as they are matched day by day. Select a tag to view its statistics.

5. PCA

Choose the tags to analyse together, the wavelet statistics to include, and whether to standardise. Calculate eigenvalues shows the variance each component explains and suggests how many to keep: those with eigenvalues of 1 or more, or more if needed to reach 70% of the variance. Choose the number of components, then Run PCA. The results are combined with the depth statistics, ready for clustering. The PCA figures can be viewed on the right.

6. Clustering

Choose the PCA results to cluster. Plot elbow and silhouette helps choose the number of clusters. Run k-means clusters the days and shows:

an interactive 3D plot of the days on the first three principal components, coloured by cluster (drag to rotate, scroll to zoom),
the mean standardised value of each variable in each cluster,
how many days of each tag are in each cluster.

A random seed makes the clusters the same each time.

7. Results

Plot each tag’s depth record with days coloured by cluster, and the most typical days of each cluster, optionally with night shaded. The time taken to make the example-day plots is shown under Create plots.

Tips

While a long step runs, a progress bar shows which tag is being processed, but the rest of the app can’t be used until the step finishes.
File and folder Browse windows open on your computer, in front of the browser. A message in the app shows while one is open.
Results are saved as each step runs, so you can close the app and pick up later by opening the same project folder.